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Introduction 


This manual describes the Application Programming Interface (API) for the NeXTStep® 

TM 

development environment. It’s part of a collection of manuals called the NeXT 
Developer’s Library, the illustration on the first page of this manual shows the complete set 
of manuals in this Library. 

In two volumes, this manual provides detailed descriptions of all classes, functions, 
operators, and other programming elements that make up the API, listed alphabetically 
within each category for easy reference. Some topics discussed here aren’t covered in 
detail; instead, you’re referred to a generally available book on the subject, or to an on-line 
source of the information (see “Suggested Reading” in the NeXT Technical Summaries 
manual. 

For many programmers, only a fraction of the information in this manual will have to be 
learned; the more sophisticated the application, the more you’ll need to understand. 

This manual assumes you’re familiar with the standard NeXT user interface. Some 
experience using a NeXT application, such as the WriteNow® word processor, would be 
helpful. 

A version of this manual is stored on-line in the NeXT Digital Library (which is described 
in the user’s manual NeXT Applications ). The Digital Library also contains Release Notes 
that provide last-minute information about the latest release of the software. 


Using Documented API 

The API described in this manual provides all the functionality you need to make full use 
of the NeXTStep software. If you have questions about using the API, this documentation 
and the NeXT Technical Support Department can help you use it correctly. If a feature in 
the API doesn’t work as described, it’s considered a bug which NeXT will work to fix. If 
API features change in future releases, these changes will be described in on-line release 
notes and printed documentation. 

Undocumented features are not part of the API. If you use undocumented features, you run 
several risks. First, your application may be unreliable, because undocumented features 
won’t work the way you expect them to in all cases. Second, NeXT Technical Support can’t 
provide full assistance in fixing problems that arise, other than to recommend that you use 
documented API. Finally, your application may be incompatible with future releases, since 
undocumented features can and will change without notice. 
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How This Manual is Organized 

The chapters in this manual are as follows: 

• Chapter 1, “Constants and Data Types,” lists constants and data types used by the 
methods, instance variables, and functions described in the remaining chapters. Not 
listed in this chapter are constants and data types specific to a particular class; these are 
documented with the associated class in Chapter 2. 

• Chapter 2, “Class Specifications,” describes the classes defined in the Application Kit 
as well as those that come with the NeXT implementation of the Objective-C language. 
Each class specification details the instance variables the class declares, the methods it 
defines, and any special constants and defined types it uses. There’s also a general 
description of the class and its place in the inheritance hierarchy. 

• Chapter 3, “C Functions,” describes in detail the C functions provided by NeXT (except 
for Mach functions). It lists the functions in two groups, NeXTStep functions and 
run-time functions. Each function’s calling sequence, its return value, and any 
exceptions it raises are given, in addition to a description of what the function does. 

• Chapter 4, “PostScript® Operators,” describes NeXT’s extensions to the Display 
PostScript® system. It also lists the standard PostScript operators that have different or 
additional effects in the NeXT implementation. 

• Chapter 5, “Data Formats,” describes the standard data formats recognized by the 
pasteboard. 

Volume 1 includes the introductory material, all of Chapter 1, and Chapter 2 through the 

OpenPanel class in the Application Kit. Volume 2 continues Chapter 2, beginning with the 

PageLayout class; it includes Chapters 3, 4, and 5 and the index. 


Conventions 

Syntax Notation 

Where this manual shows the syntax of a method, function, or other programming element, 
the use of bold, italic, square brackets [ ], and ellipsis has special significance, as described 
here. 

Bold denotes words or characters that are to be taken literally (typed as they appear). Italic 
denotes words that represent something else or can be varied. For example, the syntax 

print expression 

means that you follow the word print with an expression. 
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Square brackets [ ] mean that the enclosed syntax is optional, except when they’re bold [ ], 
in which case they’re to be taken literally. The exceptions are few and will be clear from 
the context. For example, 

pointer [filename ] 

means that you type a pointer with or without a file name after it, but 
[receiver message ] 

means that you specify a receiver and a message enclosed in square brackets. 

Ellipsis (...) indicates that the previous syntax element may be repeated. For example: 

Syntax Allows 

pointer... One or more pointers 

pointer [, pointer ] ... One or more pointers separated by commas 

pointer [filename ...] A pointer optionally followed by one or more file names 

pointer [, filename] ... A pointer optionally followed by a comma and one or more 

file names separated by commas 
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Chapter 1 

Constants and Data Types 


This chapter lists many of the constants and data types used in developing NeXTStep 
applications. This list includes constants and types defined in the /usr/include 
subdirectories objc, dpsclient, appkit, and streams. Not included are constants and types 
defined in the header files for the common classes and Application Kit classes: these are 
listed with the class descriptions in Chapter 2. 

Constants and Data Types are presented in separate sections of this chapter. Each listing 
includes a reference to the class header file where the constant or type is defined. 


Constants 

In most cases, the value defined for a constant is arbitrary; you don’t need to know the value 
to use the constant. In cases where a constant provides access to a meaningful value, the 
definition of that value is included in parentheses next to the constant’s name. 


Name 

Defined In 

CLS_CLASS 

objc/objc-class.h 

CLS_META 

objc/objc-class.h 

CLS_INITIALIZED 

objc/objc-class.h 

CLS_POSING 

objc/objc-class.h 

CLS_MAPPED 

objc/objc-class.h 

DPS_ALLCONTEXTS 

dpsclient/dpsNeXT.h 

DPS_ARRAY 

dpsclient/dpsfriends.h 

DPS_BOOL 

dpsclient/dpsfriends.h 

DPS_DEF_TOKENTYPE 

dpsclient/dpsfriends .h 

dps_errorbase 

dpsclient/dpsclienth 

DPS_EXEC 

dpsclient/dpsfriends .h 

DPS_EXT_HEADER_SIZE 

dpsclient/dpsfriends.h 

DPS_HEADER_SIZE 

dpsclient/dpsfriends.h 

DPS_HI_IEEE 

dpsclient/dpsfriends.h 

DPS_HI_NATIVE 

dpsclient/dpsfriends.h 

DPS_IMMEDIATE 

dpsclient/dpsfriends.h 

DPS_INT 

dpsclient/dpsfriends.h 

DPS_LITERAL 

dpsclient/dpsfriends.h 

DPS_LO_IEEE 

dpsclient/dpsfriends.h 

DPS_LO_NATIVE 

dpsclient/dpsfriends.h 

DPS_MARK 

dpsclient/dpsfriends.h 

DPS_NAME 

dpsclient/dpsfriends.h 
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DPS_NEXTERRORBASE 

DPS_NULL 

DPS_REAL 

DPS_STRING 

DPSSYSNAME 

FALSE 

NBITSCHAR 

NBITSINT 

nil 

Nil 

NO 

NX_ ABOVE 

NX_ALLEVENTS 

NX_ALLOC_ERROR 

NX_ALPHAMASK 

NX_ALPH AS HIFTM AS K 

NX_ALTERNATEM AS K 

NX_APPBASE 

NX_APPDEFINED 

NX_APPDEFINEDMAS K 

NX_APPKITERRBASE 

NX_ASCIISET 

nx_bad_tiff_format 

nx_below 

nx_bigendian 

NX_BLACK (0.0) 

NX_BROADCAST 

NX_BUFFERED 

NX_BYPSCONTEXT 

NX_BYTYPE 

NX__CANREAD 

NX_CANSEEK 

NX.CANWRITE 

NX_CLEAR 

NX_COLORBLACK 

NX_COLORBLUE 

NX_COLORBROWN 

NX_COLORCLEAR 

NX_COLORCYAN 

NX_COLORDKGRAY 

NX_COLORGRAY 

NX_COLORGREEN 

NX_COLORLTGRAY 

NX_COLORMAGENTA 

NX_COLORMASK 

NX_COLORORANGE 

NX_COLORPURPLE 

NX_COLORRED 

NX_COLORWHITE 

NX_COLORYELLOW 


dpsclient/dpsclient.h 

dpsclient/dpsfriends.h 

dpsclient/dpsfriends.h 

dpsclient/dpsfriends.h 

dpsclient/dpsfriends.h 

appkit/nextstd.h 

appkit/nextstd.h 

appkit/nextstd.h 

objc/objc.h 

objc/objc.h 

objc/objc.h 

dpsclient/dpsN eXT.h 

dpsclient/event.h 

appkit/tiff.h 

appkit/graphics .h 

dpsclient/event.h 

dpsclient/event.h 

appkit/errors.h 

dpsclient/event.h 

dpsclient/event.h 

appkit/errors.h 

dpsclient/event.h 

appkit/tiff.h 

dpsclient/dpsNeXT.h 

appkit/tiff.h 

appkit/graphics.h 

dpsclient/event.h 

dpsclient/dpsNeXT.h 

dpsclient/event.h 

dpsclient/event.h 

streams/streams.h 

streams/streams.h 

streams/streams.h 

dpsclient/dpsNeXT.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/graphics.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 

appkit/color.h 
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NX_COMMANDMASK 

dpsclient/event.h 

NX_COMPRESSION_NOT_YET_SUPPORTED 

appkit/tiff.h 

NX_CONTROLM AS K 

dpsclient/event.h 

NX_COPY 

dpsclient/dpsNeXT.h 

NX_CURSORUPDATE 

dpsclient/event.h 

NX_CURSORUPDATEMASK 

dpsclient/event.h 

NX_DATA 

dpsclient/dpsNeXT.h 

NX_DATOP 

dpsclient/dpsNeXT.h 

NX_DEFAULTBUFSIZE (16 * 1024) 

streams/streamsimpl.h 

NXJDIN 

dpsclient/dpsNeXT.h 

NX_DINGBATSSET 

dpsclient/event.h 

NX_DKGRAY (1.0/3.0) 

appkit/graphics.h 

NX_DOUT 

dpsclient/dpsNeXT.h 

NX_DOVER 

dpsclient/dpsNeXT.h 

NX_EOS 

streams/streams.h 

NX_EVENTCODEMASK 

dpsclient/event.h 

NX_EXPLICIT 

dpsclient/event.h 

NX_FILE_IO_ERROR 

appkit/tiff.h 

NX_FIRSTEVENT 

dpsclient/event.h 

NX_FIRSTWINDOW 

dpsclient/event.h 

NX_FLAGSCHANGED 

dpsclient/event.h 

NX_FLAGSCHANGEDMASK 

dpsclient/event.h 

NX_FONTCHARDATA 

appkit/afm.h 

NX_FONTCOMPOSITES 

appkit/afm.h 

NX_FONTHEADER 

appkit/afm.h 

NX_FONTKERNING 

appkit/afm.h 

NX.FONTMETRICS 

appkit/afm.h 

NX_FONTWIDTHS 

appkit/afm.h 

NX.FOREVER 

dpsclient/dpsNeXT.h 

NX_FORMAT_NOT_YET_SUPPORTED 

appkit/tiff.h 

NX_FREEBUFFER 

streams/streams .h 

NX_FROMCURRENT 

streams/streams.h 

NX_FROMEND 

streams/streams .h 

NXJFROMSTART 

streams/streams.h 

NX_HIGHLIGHT 

dpsclient/dpsN eXT.h 

NX_IMAGE_NOT_FOUND 

appkit/tiff.h 

NX_JOURNALEVENT 

dpsclient/event.h 

NX_JOURNALEVENTMASK 

dpsclient/event.h 

NX_KEYDOWN 

dpsclient/event.h 

NX_KEYDOWNMASK 

dpsclient/event.h 

NX_KEYUP 

dpsclient/event.h 

NX_KEYUPMASK 

dpsclient/event.h 

NX_KITDEFINED 

dpsclient/event.h 

NX_KITDEFINEDMASK 

dpsclient/event.h 

NX_LASTEVENT 

dpsclient/event.h 

NX_LASTKEY 

dpsclient/event.h 

NX_LASTLEFT 

dpsclient/event.h 

NX_LASTRIGHT 

dpsclient/event.h 

NX_LITTLEENDIAN 

appkit/tiff.h 
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NX JLMOUSEDOWN 

NX_LMOUSEDOWNMASK 

NX.LMOUSEDRAGGED 

NX_LMOU SEDRAGGEDMASK 

NX_LMOUSEUP 

NX_LMOU SEUPM ASK 

NX_LTGRAY (2.0/3.0) 

NX_MESHED 

NX_MONOTONICMASK 

NX_MOUSEDOWN 

NX_MOUSEDOWNMASK 

NX_MOUSEDR AGGED 

NX_MOUSEDRAGGEDMASK 

NX_MOUSEENTERED 

NX_MOUSEENTEREDMASK 

NX_MOUSEEXITED 

NX_MOUSEEXITEDMASK 

NX_MOUSEMOVED 

NX_MOU SEMO VEDM AS K 

NX_MOUSEUP 

NX_MOUSEUPMASK 

NX_MOUSEWINDOW 

NX_NEXTCTRLKEYMASK 

NX_NEXTLALTKEYMASK 

NX_NEXTLCMDKEYMASK 

NX_NEXTLSHIFTKEYMASK 

NX_NEXTRALTKEYMASK 

NX_NEXTRCMDKEYMASK 

NX_NEXTRSHIFTKEYMASK 

NX_NEXTWINDOW 

NX.NOALPHA 

NX_NOBUF 

NX_NONRETAINED 

NX_NOWINDOW 

NX_NULLEVENT 

NX_NULLE VENTM AS K 

NX_NUMERICPADM AS K 

NX_ONES 

NX_OUT 

NX_PAGEHEIGHT 

NX_PLANAR 

NX_PLUS 

NX_PLUSD 

NX_PLUSL 

NX_READFLAG 

NX_READONLY 

NX_READ WRITE 

NX_RETAINED 

NX.RMOUSEDOWN 

NX_RMOUSEDOWNMASK 
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dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

appkit/graphics .h 

appkit/graphics.h 

appkit/graphics.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/eventh 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/eventh 

dpsclient/event.h 

dpsclient/eventh 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

appkit/color.h 

streams/streams.h 

dpsclient/dpsNeXT.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/eventh 

dpsclient/event.h 

dpsclient/dpsNeXT.h 

dpsclient/dpsNeXT.h 

appkit/tiff.h 

appkit/graphics.h 

dpsclient/dpsNeXT.h 

dpsclient/dpsNeXT.h 

dpsclient/dpsNeXT.h 

streams/streams .h 

streams/streams .h 

streams/streams.h 

dpsclient/dpsNeXT.h 

dpsclient/event.h 

dpsclient/event.h 



NX_RMOUSEDR AGGED 

NX_RMOUSEDRAGGEDMASK 

NX.RMOUSEUP 

NX_RMOUSEUPMASK 

NX_SATOP 

NX_SAVEBUFFER 

NX_SHIFTMASK 

NX_SIN 

NX_SOUT 

NX_SOVER 

NX_STREAMERRBASE 

NX_S YMB OLSET 

NX_S Y SDEFINED 

NX_S Y SDEFINEDMASK 

NX_TIFF_CANT_APPEND 

NX_TIFF_COMPRESSION_CCITFAX3 

NX_TIFF_COMPRESSION_JPEG 

NX_TIFF_COMPRESSION_LZW 

NX_TIFF_COMPRESSION_NEXT 

NX_TIFF_COMPRESSION_NONE 

NX_TIFF_COMPRESSION_PACKBITS 

NX_TIMER 

NX_TIMERMASK 

NX_TOPWINDOW 

NX_TRANSMIT 

NX_TRUNCATEBUFFER 

NX_UNIQUEALPHABITMAP 

NX_UNIQUEBITMAP 

NX_USER_OWNS_BUF 

NX_WHITE (1.0) 

NX_WRITEFLAG 

NX_WRITEONLY 

NX_XMAX 

NX_XMIN 

NX_XOR 

NX_YMAX 

NX_YMIN 

NXSYSTEM VERSION 
NXS Y STEMVERSION082 
NXS Y STEMVERSION083 
NXS Y STEMVERSION090 
NXSYSTEMVERSION0900 
NXS Y STEMVERSION0901 
NXSYSTEMVERSION0905 
NXS Y STEMVERSION0930 
TRUE 

TYPEDSTREAM_ERROR_RBASE 

YES 


dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/dpsNeXT.h 

streams/streams .h 

dpsclient/event.h 

dpsclient/dpsNeXT.h 

dpsclient/dpsNeXT.h 

dpsclient/dpsNeXT.h 

streams/streams .h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

appkit/tiff.h 

appkit/tiff.h 

appkit/tiff.h 

appkit/tiff.h 

appkit/tiff.h 

appkit/tiff.h 

appkit/tiff.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

dpsclient/event.h 

streams/streams.h 

appkit/obsoleteBitmap.h 

appkit/obsoleteBitmap.h 

streams/streams.h 

appkit/graphics.h 

streams/streams .h 

streams/streams .h 

appkit/graphics .h 

appkit/graphics.h 

dpsclient/dpsNeXT.h 

appkit/graphics.h 

appkit/graphics.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

objc/typedstream.h 

appkit/nextstd.h 

objc/typedstream.h 

objc/objc.h 
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Data Types 


BOOL 

DEFINED IN objc/objc.h 

typedef char BOOL; 


Cache 

DEFINED IN objc/objc-class.h 


typedef struct objc_cache *Cache; 


Category 

DEFINED IN objc/objc-class.h 

typedef struct objc_category ^Category; 


Class 

DEFINED IN objc/objc.h 

typedef struct objc_class *Class; 


DPSBinObjRec 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
union { 

long int integerVal; 
float realVal; 

long int nameVal; /* offset or index */ 

long int booleanVal; 

long int stringVal; /* offset */ 

long int arrayVal; /* offset */ 

} val; 

} DPSBinObjRec, *DPSBinObj; 
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DPSBinObj Generic 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
long int val; 

} DPSBinObjGeneric; 

DPSBinObjReal 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
float realVal; 

} DPSBinObjReal; 

DPSBinObj SeqRec 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

unsigned char tokenType; 
unsigned char nTopElements; 
unsigned short length; 

DPSBinObjRec objects[1]; 

} DPSBinObjSeqRec, *DPSBinObjSeq; 



DPSContextRec 


DEFINED IN dpsclient/dpsfriends.h 

typedef struct _t_DPSContextRec { 
char *priv; 

DPSSpace space; 

DPSProgramEncoding programEncoding; 

DPSNameEncoding nameEncoding; 
struct _t_DPSProcsRec const * procs; 
void (*textProc)(); 
void (*errorProc)(); 

DPSResults resultTable; 
unsigned int resultTableLength; 

struct __t_DPSContextRec *chainParent, *chainChild; 

DPSContextType type; /* NeXT addition - denotes type of context */ 

} DPSContextRec, *DPSContext; 

DPSContextType 

DEFINED IN dpsclient/dpsfriends.h 

typedef enum { /* NeXT addition */ 

dps_machServer,/* a mach binary connection to a window server */ 
dps_fdServer, /* a socket binary connection to a window server */ 
dps_stream /* an ascii NXStream *./ 

} DPSContextType; 

DPSDefinedType 

DEFINED IN dpsclient/dpsfriends.h 

typedef enum { 

dps_tBoolean, 
dps_tChar, dps_tUChar, 
dps_tFloat, dps_tDouble, 
dps_tShort, dps_tUShort, 
dps_tlnt, dps__tUInt, 

dps_tLong, dps_tULong } DPSDefinedType; 
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DPSErrorCode 


DEFINED IN dpsclient/dpsclient.h 

typedef enum _DPSErrorCode { 

dps_err_ps = DPS_ERRORBASE, 

dps_err_nameTooLong, 

dps_err_resultTagCheck, 

dps_err_resultTypeCheck, 

dps_err_invalidContext, 

dps_err_select = DPS_NEXTERRORBASE, 

dps_err_connectionClosed, 

dps_err_read, 

dps_err_write, 

dps_err_invalidFD, 

dps_err_invalidTE, 

dps_err__invalidPort, 

dps_err_outOfMemory, 

dps_err_cantConnect 

} DPSErrorCode; 


DPSErrorProc 

DEFINED IN dpsclient/dpsclient.h 

typedef void (*DPSErrorProc)( 

DPSContext ctxt, 

DPSErrorCode errorCode, 
long unsigned int argl, 
long unsigned int arg2 ); 


DPSEventFilterFunc 

DEFINED IN dpsclient/dpsNeXT.h 

typedef int (^DPSEventFilterFunc)( NXEvent *ev ); 

DPSExtendedBinObjSeq 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

unsigned char tokenType; 

unsigned char escape; /* zero if this is an extended sequence */ 
unsigned short nTopElements; 
unsigned long length; 

DPSBinObjRec objects[1]; 

} DPSExtendedBinObjSeqRec, *DPSExtendedBinObjSeq; 
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DPSFDProc 


DEFINED IN dpsclient/dpsNeXT.h: 

typedef void (*DPSFDProc)( int fd, void *userData ); 


DPSNameEncoding 

DEFINED IN dpsclient/dpsfriends.h 

typedef enum { 
dps_indexed, 
dps_strings 
} DPSNameEncoding; 


DPSNumberFormat 

DEFINED IN dpsclient/dpsNeXT.h 

typedef enum _DPSNumberFormat { 
dps_float = 48, 
dps_long = 0, 
dps_short = 32 
} DPSNumberFormat; 


DPSPortProc 

DEFINED IN dpsclient/dpsNeXT.h 

typedef void (*DPSPortProc) ( msg_header_t *msg, void *userData ) 


DPSProcs 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct _t__DPSProcsR.ec { 
void (*BinObjSeqWrite)( 

DPSContext ctxt, 
const void *buf, 
unsigned int count ) ; 
void (*WriteTypedObjectArray)( 

DPSContext ctxt, 

DPSDefinedType type, 
const void *array, 
unsigned int length ) ; 
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void (*WriteStringChars)( 

DPSContext ctxt, 
const char *buf, 
unsigned int count ) ; 
void (*WriteData)( 

DPSContext ctxt, 
const void *buf, 
unsigned int count ) ; 
void (*WritePostScript)( 

DPSContext ctxt, 
const void *buf, 
unsigned int count ) ; 
void (*FlushContext) ( DPSContext ctxt ); 
void (*ResetContext)( DPSContext ctxt ); 
void (*UpdateNameMap)( DPSContext ctxt ); 
void (*AwaitReturnValues)( DPSContext ctxt ) 
void (*Interrupt)( DPSContext ctxt ); 
void (*DestroyContext)( DPSContext ctxt ); 
void (*WaitContext)( DPSContext ctxt ); 
void (*Printf)( 

DPSContext ctxt, 
const char *fmt, 
va_list argList ) ; 

} DPSProcsRec, *DPSProcs; 


DPSProgramEncoding 

DEFINED IN dpsclient/dpsfriends.h 

typedef enum { 
dps_ascii, 
dps_binObjSeq, 
dps_encodedTokens 
} DPSProgramEncoding; 


DPSResultsRec 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

DPSDefinedType type; 
int count; 
char *value; 

} DPSResultsRec, *DPSResults; 



DPSSpaceRec 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct { 

int lastNamelndex; 

struct _t_DPSSpaceProcsR.ec const * procs; 

} DPSSpaceRec, *DPSSpace; 


DPSSpaceProcsRec 

DEFINED IN dpsclient/dpsfriends.h 

typedef struct _t_DPSSpaceProcsRec { 

void (*DestroySpace)( DPSSpace space ); 

/* See DPSDestroySpace() in dpsclient.h */ 

} DPSSpaceProcsRec, *DPSSpaceProcs; 

DPSTextProc 

DEFINED IN dpsclient/dpsclient.h 

typedef void (*DPSTextProc) ( 

DPSContext ctxt, 
const char *buf, 
long unsigned int count ); 


DPSTimedEntry 

DEFINED IN dpsclient/dpsNeXT.h 


typedef struct _DPSTimedEntry *DPSTimedEntry; 
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DPSUserPathAction 


DEFINED IN dpsclient/dpsNeXT.h 

typedef enum _DPSUserPathAction { 
dps_uappend = 176, 
dps_ufill = 179, 
dps_ueofill = 178, 
dps_ustroke = 183, 
dps_ustrokepath = 364, 
dps_inufill = 93, 
dps_inueofill = 92, 
dps_inustroke = 312, 
dps_def = 51, 
dps_put = 120 
} DPSUserPathAction; 

DPSUserPathOp 

DEFINED IN dpsclient/dpsNeXT.h 

typedef enum _DPSUserPathOp { 
dps_setbbox = 0, 
dps_moveto, 
dps_rmoveto, 
dps_lineto, 
dps_rlineto, 
dps_curveto, 
dps_rcurveto, 
dps_arc, 
dps_arcn, 
dps_arct, 
dps_closepath, 
dps_ucache 
} DPSUserPathOp; 


id 

DEFINED IN objc/objc.h 

typedef struct objc_object { 

Class isa; 

} *id; 

IMP 

DEFINED IN objc/objc.h 


typedef id (*IMP)(id, SEL, ...); 



Ivar 


DEFINED IN objc/objc-class.h 

typedef struct objc_ivar *Ivar; 


Method 

DEFINED IN objc/objc-class.h 

typedef struct objc_method ^Method; 


Module 

DEFINED IN objc/objc-runtime.h 

typedef struct objc_module *Module; 


NXAppkitErrorTokens 

DEFINED IN appkit/errors.h 

typedef enum _NXAppkitErrorTokens { 

NX_longLine = NX_APPKITERRBASE, 

NX_nullSel, /* Text, operation attempted on empty 

selection */ 

NX_wordTablesWrite, /* error while writing word tables */ 

NX_wordTablesRead, /* error while reading word tables */ 

NX__textBadRead, /* Text, error reading from file */ 

NX_textBadWrite, /* Text, error writing to file */ 

NX_powerOff, /* poweroff */ 

NX_pasteboardComm, /* communications prob with pbs server */ 
NX_mallocError, /* malloc problem */ 

NX_printingComm, /* sending to npd problem */ 

NX__abortModal, /* used to abort modal panels */ 

NX_abortPrinting, /* used to abort printing */ 

NX_illegalSelector, /* bogus selector passed to appkit */ 
NX_appkitVMError, /* error from vm_ call */ 

NX_badRtfDirective, 

NX_badRtfFontTable, 

NX_badRtfStyleSheet, 

NX_newerTypedStream, 

NX_tiffError 
} NXAppkitErrorTokens; 
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NXAtom 


DEFINED IN objc/hashtable.h 

typedef const char *NXAtom; 


NXCharMetrics 

DEFINED IN appkit/afm.h 

typedef struct { /* per character info */ 

short charCode; 
unsigned char numKernPairs; 
unsigned char reserved; 
float xWidth; 
int name; 
float bbox[4]; 
int kernPairlndex; 

} NXCharMetrics; 

NXChunk 

DEFINED IN appkit/chunk.h 

typedef struct _NXChunk { 

short growby; /* increment to grow by */ 

int allocated; /* how much is allocated */ 

int used; /* how much is used */ 

} NXChunk; 

NXColor 

DEFINED IN appkit/color.h 

typedef struct _NXColor { 

unsigned short colorField[8]; 

} NXColor; 
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NXCoIorSpace 
DEFINED IN 


appkit/graphics.h 

typedef enum _NXColorSpaceType { 

NX_ONEISBLACK_COLORSPACE = 0, /* monochrome, 1 is black */ 
NX_ONEISWHITE_COLORSPACE =1, /* monochrome, 1 is white */ 
NX_RGB_COLORSPACE = 2, 

NX_CMYK_COLORSPACE = 5 
} NXCoIorSpace; 


NXCompositeChar 

DEFINED IN appkit/afm.h 

typedef struct { /* a composite char */ 

int numParts; 
int firstPartIndex; 

} NXCompositeChar; 


NXCompositeCharPart 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the composite char array */ 

int part Index; 
float dx; 
float dy; 

} NXCompositeCharPart; 

NXCoord 

DEFINED IN dpsclient/event.h 

typedef float NXCoord 
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NXDefaults Vector 


DEFINED IN appkit/defaults.h 

typedef struct _NXDefault { 
char *name; 
char *value; 

} NXDefaultsVector[]; 

NXEncodedLigature 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the encoded ligature array */ 

unsigned char firstChar; 
unsigned char secondChar; 
unsigned char ligatureChar; 
unsigned char reserved; 

} NXEncodedLigature; 

NXErrorReporter 

DEFINED IN appkit/errors.h 

typedef void NXErrorReporter(NXHandler *errorState); 

NXEvent 

DEFINED IN dpsclient/event.h 

typedef struct _NXEvent { 

int type; /* An event type from above */ 

NXPoint location; 

/* Base coordinates in window, from lower-left */ 
long time /* vertical intervals since launch */ 

int flags; /* key state flags */ 

unsigned int window; /* window number of assigned window */ 
NXEventData data; /* type-dependent data */ 

DPSContext ctxt; /* context the event came from */ 

} NXEvent, *NXEventPtr; 
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NXEventData 


DEFINED IN dpsclient/event.h 

typedef union { 

struct { /* For mouse-down and mouse-up events */ 

short reserved; 

short eventNum; /* unique identifier for this button */ 
int click; /* click state of this event */ 

int unused; 

} mouse; 

struct { /* For key-down and key-up events */ 

short reserved; 

short repeat; /* for key-down: nonzero if really a repeat */ 
unsigned short charSet; /* character set code */ 

unsigned short charCode; /* character code in that set */ 

unsigned short keyCode; /* device-dependent key number */ 

short keyData; /* device-dependent info */ 

} key; 

struct { /* For mouse-entered and mouse-exited events */ 

short reserved; 

short eventNum; 

/* unique identifier from mouse down event */ 
int trackingNum; /* unique identifier from 

settrackingrect */ 

int userData; /* uninterpreted integer from 

settrackingrect */ 

} tracking; 

struct { /* For appkit-defined, sys-defined, and app-defined 

events */ 
short reserved; 

short subtype; /* event subtype for compound events */ 
union { 


float 

F[2] ; 

/* 

for 

use 

in 

compound 

events 

*/ 

long 

L[2] ; 

/* 

for 

use 

in 

compound 

events 

*/ 

short 

S[4] ; 

/* 

for 

use 

in 

compound 

events 

*/ 

char 

C [8] ; 

/* 

for 

use 

in 

compound 

events 

*/ 


} misc; 

} compound; 

} NXEventData; 

NXExceptionRaiser 

DEFINED IN objc/error.h 

typedef void NXExceptionRaiser(int code, 

const void *datal, 
const void *data2); 
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NXFontMetrics 


DEFINED IN 


appkit/afm.h 


typedef struct _NXFontMetrics { 
char *formatVersion; 
char *name; 
char *fullName; 
char *familyName; 
char ^weight; 
float italicAngle; 
char isFixedPitch; 
char isScreenFont; 
short screenFontSize; 
float fontBBox[4]; 
float underlinePosition; 
float underlineThickness; 
char *version; 
char *notice; 
char *encodingScheme; 
float capHeight; 
float xHeight; 
float ascender; 
float descender; 
short hasYWidths; 
float ^widths; 
unsigned int widthsLength; 
char *strings; 


/* version of afm file format */ 

/* name of font for findfont */ 

/* full name of font */ 

/* "font family" name */ 

/* weight of font */ 

/* degrees ccw from vertical */ 

/* is the font mono-spaced? */ 

/* is the font a screen font? */ 

/* If it is, how big is it? */ 

/* bounding box (llx lly urx ury) */ 

/* dist from basline for underlines */ 
/* thickness of underline stroke */ 

/* version identifier */ 

/* trademark or copyright */ 

/* default encoding vector */ 

/* top of 'H' */ 

/* top of ' x' */ 

/* top of ' d' */ 

/* bottom of 'p' */ 

/* do any chars have non-0 y width? */ 
/* character widths in x */ 

/* table of strings and other info */ 


unsigned int stringsLength; 

char hasXYKerns; /* Do any of the kern pairs have nonzero dy? 
char reserved; 

short ^encoding; /* 256 offsets into charMetrics */ 

float *yWidths; 

/* character widths in y. NOT in encoding */ 

/* order, but a parallel array to the charMetrics array */ 


NXCharMetrics 

int 

NXLigature 

int 

NXEncodedLigature 

int 


^charMetrics; /'■ 

numCharMetrics; /' 

*ligatures; /'■ 

numLigatures; 
*encLigatures; /■ 


numEncLigatures; /* 


array of NXCharMetrics : 
num elements */ 
array of NXLigatures */ 
/* num elements */ 
array of 

NXEncodedLigatures */ 
num elements */ 
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} 


union { 


NXKernPair 

*kernPairs; 

/* 

NXKernXPair 

*kernXPairs; 

/* 

} kerns; 

int 

numKernPairs ; 

/* 

NXTrackKern 

*trackKerns; 

/* 

int 

numTrackKerns; 

/* 

NXCompositeChar 

*compositeChars; 

/* 

int 

numCompositeChars ; 



NXCompositeCharPart *compositeCharParts; 


int numCompositeCharParts; 
NXFontMetrics; 


array of NXKernPairs */ 
array of NXKernXPairs */ 

num elements */ 
array of NXTrackKerns */ 
num elements */ 
array of 

NXCompositeChar */ 

/* num elements */ 

/* array of 

NXCompositeCharPart */ 
/* num elements */ 


NXHandler 


DEFINED IN objc/error.h 


typedef struct _NXHandler { 

jmp_buf jumpState; 

struct _NXHandler *next; 
int code; 

const void *datal, *data2; 

} NXHandler; 


/* a node in the handler chain */ 
/* place to longjmp to */ 

/* ptr to next handler */ 

/* error code of exception */ 

/* blind data for describing */ 

/* error */ 


NXHashState 

DEFINED IN objc/hashtable.h 

typedef struct {int i; int j;} NXHashState; 


NXHashTablePrototype 

DEFINED IN objc/hashtable.h 

typedef struct { 

unsigned (*hash)(const void *info, const void *data); 
int (*isEqual)(const void *info, const void *datal, 

const void *data2); 

void (*free)(const void *info, void *data); 

int style; /* reserved for future expansion; currently 0 */ 

} NXHashTablePrototype; 


Chapter 1: Constants and Data Types 



NXImagelnfo 

DEFINED IN appkit/tiff.h 


typedef struct 
int width; 
int height; 
int bitsPerSample; 
int samplesPerPixel; 
int planarConfig; 


NXImagelnfo { 

/* image width in pixels */ 

/* image height in pixels */ 

/* number of bits per data channel */ 

/* number of channels per pixel */ 

/* NX MESHED for mixed data channels */ 


/* NX_PLANAR for separate data planes */ 


int photolnterp; 

/* interpretations 
} NXImagelnfo; 


/* various bits set for various photometric */ 


NXKernPair 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the kern pair array */ 

int secondCharlndex; 
float dx; 
float dy; 

} NXKernPair; 


NXKernXPair 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the kern X pair array */ 

int secondCharlndex; 
float dx; 

} NXKernXPair; 


NXLigature 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the ligature array */ 

int firstCharlndex; 
int secondCharlndex; 
int ligaturelndex; 

} NXLigature; 
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NXPoint 


DEFINED IN dpsclient/event.h 

typedef struct _NXPoint { /* point */ 

NXCoord x, y; 

} NXPoint; 


NXPrintfProc 

DEFINED IN streams/streams.h 

typedef void NXPrintfProc(NXStream *stream, void *item, 

void *procData); 


NXRect 

DEFINED IN appkit/graphics.h 

typedef struct _NXRect { 

NXPoint origin; 

NXSize size; 

} NXRect; 

NXScreen 

DEFINED IN appkit/screens.h 

typedef struct _NXScreen { 


int 

screenNumber; 

/* 

/* 

Screen number (may be used as */ 
argument to framebuffer op). */ 

NXRect 

screenBounds; 

/* 

Bounds of the screen. */ 

short 

reservedShort[6] 

; 

/* Don't use these. */ 

NXWindowDepth 

depth; 

/* 

Depth of the frame buffer */ 

int 

reserved[3]; 

/* 

Don't use these either. */ 


} NXScreen; 

NXSize 

DEFINED IN dpsclient/event.h 

typedef struct _NXSize { /* size */ 

NXCoord width, height; 

} NXSize; 
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NXStream 


DEFINED IN streams/streams.h 

typedef struct _NXStream { 

unsigned int magic_number;/* to check stream validity */ 

unsigned char *buf_base; /* data buffer */ 

unsigned char *buf_ptr; /* current buffer pointer */ 

int buf_size; /* size of buffer */ 

int buf_left; /* # left till buffer operation */ 

long offset; /* position of beginning of buffer */ 

int flags; /* info about stream */ 

int eof; 

const struct stream_functions ^functions; /* functions to 

implement stream */ 

void *info; /* stream specific info */ 

} NXStream; 


NXStreamErrors 

DEFINED IN streams/streams.h 

typedef enum _NXStreamErrors { 

NX_illegalWrite = NX_STREAMERRBASE, 

NX_illegalRead, 

NX_illegalSeek, 

NX_illegalStream, 

NX_streamVMError 
} NXStreamErrors; 

NXTIFFInfo 

DEFINED IN appkit/tiff.h 

typedef struct _NXTIFFInfo { 
int imageNumber; 

NXImagelnfo image; 

int subfileType; /* only subfileType = 1 is supported */ 
int rowsPerStrip; 
int stripsPerlmage; 

int compression; /* compression id, 1 = no compression */ 

int numlmages; /* number of images in tiff */ 

int endian; /* either NX_BIGENDIAN or NX_LITTLEENDIAN */ 

int version; /* tiff version */ 

int error; 

int firstIFD; /* offset of first IFD entry */ 

unsigned int stripOffsets[NX_PAGEHEIGHT]; 
unsigned int stripByteCounts[NX_PAGEHEIGHT]; 

} NXTIFFInfo; 
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NXTopLevelErrorHandler 
DEFINED IN 


appkit/errors.h 

typedef void NXTopLevelErrorHandler(NXHandler *errorState) 


NXTrackingTimer 

DEFINED IN appkit/timer.h 

typedef struct _NXTrackingTimer { 
double delay; 
double period; 

DPSTimedEntry te; 

BOOL freeMe; 

BOOL firstTime; 

NXHandler *errorData; 
int reservedl; 
int reserved2; 

} NXTrackingTimer; 

NXTrackKern 

DEFINED IN appkit/afm.h 

typedef struct { /* elements of the track kern array */ 

int degree; 
float minPointSize; 
float minKernAmount; 
float maxPointSize; 
float maxKernAmount; 

} NXTrackKern; 

NXI^pedStream 

DEFINED IN objc/typedstream.h 

typedef void NXTypedStream; 

NXUncaughtExceptionHandler 

DEFINED IN objc/error.h 

typedef void NXUncaughtExceptionHandler(int code, 

const void *datal, 
const void *data2) 
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SEL 

DEFINED IN objc/objc.h 


typedef struct objc_selector *SEL; 


STR 

DEFINED IN objc/objc.h 


typedef char *STR; 


Symtab 

DEFINED IN objc/objc-runtime.h 


typedef struct objc_symtab *Symtab; 


TypedstreamErrors 

DEFINED IN objc/typedstream.h 

enum TypedstreamErrors { 

TYPEDSTREAM_CALLER_ERROR = TYPEDSTREAM_ERROR_RBASE, 
TYPEDSTREAM_FILE_INCONSISTENCY, 

TYPEDSTREAM_CLASS_ERROR, 
TYPEDSTREAM_TYPE_DESCRIPTOR_ERROR, 
TYPEDSTREAM_WRITE_REFERENCE_ERROR, 
TYPEDSTREAM_INTERNAL_ERROR. 

} ; 
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Chapter 2 

Class Specifications 


This chapter describes each of the classes defined in the Application Kit, as well as the 
classes that come with the NeXT compiler for the Objective-C language. The classes that 
come with the compiler can be used with any kit (and in programs that don’t use the kits). 

Each class specification details the instance variables the class declares, the methods it 
defines, and any special constants and defined types it uses. There’s also a general 
description of the class and its place in the inheritance hierarchy. However, you won’t find 
a discussion of any kit’s design or an explanation of how to go about using the kit to 
program an application. You may occasionally encounter terms that assume some prior 
knowledge about the kits, Mach, the Display PostScript system, or object-oriented 
programming. These topics are covered in other volumes of the NeXT Developer’s Library. 


How to Read the Specifications 

The class specifications are organized in two groups: common classes and Application Kit 
classes. Within each of these groups, the specifications are arranged in alphabetical order 
by class. 


Organization 

Information about a class is presented under the following headings: 


INHERITS FROM 

The first line of a class specification lists the classes that the class being described 
inherits from. For example: 

Panel : Window : Responder : Object 

The first class listed (Panel, in this example) is the class’s superclass. The last class 
listed is always Object, the root of all inheritance hierarchies. The classes between 
show the chain of inheritance from Object to the superclass. (This particular example 
shows the inheritance hierarchy for the Menu class of the Application Kit.) 
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DECLARED IN 


Each class lists the directory and header file in which its interface is declared. 

In the Application Kit, a master header file includes almost all the other header files you 
need to program with the kit: 

/usr/include/appkit/appkit.h 

There’s also a master header file for the classes that come with the compiler: 
/usr/include/objc/objc.h 

If you include the master header file for the Application Kit, you don’t need to also 
include this file; it’s included by the kit file. 

Because the kits are written in the Objective-C language, they make use of constants 
and types defined in the principal header file for Objective-C, objc.h. Only a handful 
of these constants and types are used by the kits, but they’re used pervasively. For 
convenience, they’re listed below. 

Defined Types: 

id 

STR 

SEL 


BOOL 
Constants: 

nil A null object id, (id)0. 

YES Boolean true, (BOOL) 1. 

NO Boolean false, (BOOL)O. 


An object. 

A C string. STR is a shorthand for (char *). It’s used only for an 
array of characters that’s terminated by the null character. 

A method selector. SEL is another shorthand for (char *), where 
the character string can be thought of as a method name. However, 
SEL is used only as a unique code for a method name, rather than 
as a pointer to an actual occurrence of the name in memory. 
Values should be assigned to SEL variables only with the 
(©selector operator: 

SEL aMethod; 

aMethod = @selector(moveTo::); 

This allows selectors to be tested by matching the value of a SEL 
code, rather than by comparing all the characters in a string. 

A char that holds one of two values: YES (true) or NO (false). 


2-4 Chapter 2: Class Specifications 



CLASS DESCRIPTION 


This section gives a general description of the class. It tells how the class fits into the 
general design of its kit and how your application can make use of it. 

• Some classes define “off-the-shelf’ objects: Your program can create direct 
instances of the class, or modify it in a subclass definition. 

• Other classes are “abstract superclasses”: You wouldn’t create an instance of the 
class itself, but only of its subclasses. The kits define some subclasses for each 
abstract superclass; others can be defined by your application. 

Occasionally, the class description will recommend that you define a subclass of a kit 
class, even though the kit class isn’t abstract. The subclass allows you to customize an 
object to the needs of your application. 


INSTANCE VARIABLES 

The instance variables that are incorporated into each object belonging to the class, 
including instance variables inherited from other classes, are listed next. The first 
instance variable in all the lists is one inherited from the Object class, isa. isa identifies 
the class that an object belongs to for the run-time system; it should never be altered or 
read directly. 

After all the instance variables are listed, those declared in the class being described are 
explained. 

However, instance variables that are for the internal use of the class are neither listed 
nor explained. These instance variables all begin with an underscore (_) to prevent 
collisions with names that you might choose for instance variables in a subclass you 
define. 


METHOD TYPES 

Methods are next listed by name and grouped by type—for example, methods used to 
draw are listed separately from methods used to handle events. This directory includes 
all the principal methods defined in the class and some that are defined in classes it 
inherits from. Inherited methods are followed by the name of the class where they’re 
defined; they’re included in the directory to let you know which inherited methods you 
might commonly use with instances of the class and where to look for a description of 
those methods. 
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CLASS METHODS 
INSTANCE METHODS 


A detailed description of each method defined in the class follows the classification by 
type. Methods that are used by class objects are presented first; if a class has no class 
methods, this section is left out. Methods that are used by instances (the objects 
produced by the class) are presented next. The descriptions within each group are 
ordered alphabetically by method name. 

Each description begins with the syntax of the method’s arguments and return values, 
continues with an explanation of the method, and ends, where appropriate, with a list 
of other related methods. Where a related method is defined in another class, it’s 
followed by the name of the other class within parentheses. 

Some methods listed in a class specification are prototypes for methods that you may 
want to implement in a subclass. A prototype is declared in the header file, but not 
actually implemented by the class. The description for such methods states that they 
are prototypes and describes the behavior and return value you should implement for 
the method. 

All methods except prototypes have reliable return values which are included in the 
method description. Many methods return self; this allows you to chain messages 
together: 

[[[receiver message 1] message2] message3 ]; 

Internal methods used to implement the class aren’t listed. Since you shouldn’t 
override any of these methods, or use them in a message, they’re excluded from both 
the method directory and the method descriptions. However, you may encounter them 
when looking at the call stack of your program from within the debugger. A private 
method is easily recognizable by the underscore (_) that begins its name. 


METHODS IMPLEMENTED BY ANOTHER OBJECT 

If a class lets you define another object—a delegate—that can intercede on behalf of 
instances of the class, the methods that the delegate can implement are described in a 
separate section. These are not methods defined in the class; rather, they’re methods 
that you can define to respond to messages sent to the delegate. 

If you define one of these methods, the delegate will receive automatic messages to 
perform it at the appropriate time. For example, if you define a 
windowDidBecomeKey: method for a Window’s delegate, the delegate will receive 
windowDidBecomeKey: messages whenever the Window becomes the key window. 

Messages are sent only if the delegate has a method that can respond. If you don’t 
define a windowDidBecomeKey: method, no message will be sent. 
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Only certain classes provide for a delegate. In the Application Kit, they are: 

Application 

Listener 

NXBrowser 

Speaker 

Text 

Window 

You can set a delegate for instances of these classes or for instances that inherit from 
these classes. 

Some class specifications have separate sections with titles such as “Methods 
Implemented by the SuperView” or “Methods Implemented by the Owner.” The 
methods described in these sections need to be implemented by another object, such as 
the superview of an instance of that class or, in the case of the Pasteboard, the owner of 
the Pasteboard instance. For example, the Clip View’s superview needs to define the 
scrollCliprto: method to coordinate scrolling of multiple Clip Views. The owner of the 
Pasteboard should define provideData: if certain promised data types won’t be 
immediately written to the Pasteboard. As is the case with the delegate methods, you 
won’t invoke these methods directly; messages to perform them will be sent 
automatically when needed and only if they’ve been defined. 


CONSTANTS AND DEFINED TYPES 

If a class makes use of symbolic constants or defined types that are specific to the class, 
they’re listed in the last section of the class specification. Defined types are likely to 
show up in instance variable declarations, and as return and parameter types in method 
declarations. Symbolic constants typically define permitted return and argument 
values. 


Method Descriptions 

By far, the major portion of each class specification is the description of methods defined 
in the class. When reading these descriptions, be especially attentive to four kinds of 
information that affect how the method can be used: 

• Whether you should implement your own version of the method 

• Whether you should have your version of the method include the kit-defined version 

• Which method is a class’s designated initializer, the method to override if you 
implement a subclass that performs initialization 

• Whether you should ever send a message to an object to perform the method 
The next four sections examine these questions. 
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Implementing Your Own Version of a Method 

For the most part, the methods in a class definition act as a private library for objects 
belonging to that class. Just as programmers generally don’t replace functions in the 
standard C library with their own versions, you generally wouldn’t write your own versions 
of the methods provided for a class. 

However, to add specific behavior to your application, you must override some of the 
methods that are defined in the kits. Often, the kit-defined method will do little or nothing 
that’s of use to your application, but it will appear in messages initiated by other methods. 
To give content to the method, your application must implement its own version. 

To override a kit method with one of your own design, simply define a subclass of the 
appropriate class and redefine the method. For example, the interface declaration for the 
Circle View class illustrated below shows that it does nothing more than override the View 
class’s drawSelf:: method. 


©interface CircleView : View { } 

- drawSelf:(NWRect *)drawRects : (int)rectCount; 
©end 


CircleView objects will perform its version of drawSelf:: rather than the empty default 
version defined in View. 

In contrast to methods that must be overridden, some methods should never be changed by 
the application. The kit depends on these methods doing just what they’re currently 
programmed to do—nothing more and nothing less. While your application can use these 
methods, it’s important that you don’t override them when defining a subclass. 

Most methods fit between these two extremes: They can be overridden, but it’s not 
necessary for you to do so. If a method description is silent on the question of overriding 
the kit method, you can be certain that it fits into this middle category. It’s a method that 
you can override, but like a function in the C library, you normally would have no reason to. 

If a method is designed to be overridden, or if it should never be overridden, the method 
description explicitly says so. 


Retaining the Kit’s Version of a Method 

Some methods can be overridden, but only to add behavior, not to alter the default actions 
of the kit-defined method. When your application overrides one of these methods, it’s 
important that it incorporate the very method it overrides. This is done by messaging super 
to perform the kit-defined version of the method. For example, if you write a new version 
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of the kit method that moves a Window, you’d most likely still want it to move a Window. 
The easiest way to have it do that is to include the old method in the new one through a 
message to super. 


- moveTo:(NWCoord)x :(NWCoord)y { 

[super moveTo:x :y]; 

/* your code goes here */ 

} 

You may occasionally be required to implement a new version of a method while preserving 
the behavior of the method you override. An example is the write: method, which archives 
an object by writing it to a typed stream. When you define a kit subclass, you may need to 
implement a version of this method that can archive the instance variables your subclass 
declares. So that a write: message will archive all of an object’s instance variables, not just 
those declared in the subclass, your version of the method should begin by incorporating 
the version used by its superclass. 


- write:(NXTypedStream *)stream { 

[super write:stream]; 

/* your code goes here */ 

} 

Method descriptions explicitly mention that you should incorporate a method you override 
only when it’s not obvious that you should preserve the default behavior in the new method. 


Designated Initializer Methods 

Initializer methods (those that begin with init...) initialize a new instance of a class by 
setting values for instance variables, creating support objects, and so on. Before a new 
instance receives class-specific initialization, it must be initialized as an instance of each 
class from which it inherits, in order, beginning with Object. To maintain this sequence, 
each common and Application Kit class has designated initializers, init... methods that 
invoke a designated initializer in the superclass before doing their work. Since Object is 
the root of the inheritance hierarchy, its designated initializer, the init method, is always the 
first method to initialize an object. The designated initializer for most other classes is the 
init... method with the most arguments (some classes have more than one designated 
initializer to perform different types of initialization). Other init... methods for a class 
initialize objects by invoking a designated initializer. Designated initializers are identified 
in their method descriptions. 

In its discussion of the alloc and init methods, the Object class specification provides more 
detail on how new instances are allocated and initialized. This discussion includes some 
guidelines to follow when writing initializer methods in a subclass. 
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Sending a Message to Perform a Method 

Some methods should never appear as messages in the code you write; you should never 
directly ask an object to perform the method. Typically, these are methods that your 
application will use indirectly, through other methods. 

Most of these methods begin with a underscore and are treated as class-internal methods. 
However, some don’t have an underscore and are included in the method descriptions. 
These are methods that your application can implement, even though it won’t directly use 
them in a message. The messages to perform these methods originate in the kit. 

The most notable example of this is the drawSelf:: method that draws a View. Although 
you must implement a drawSelf:: method for each View subclass you define, your code 
should never send a drawSelf:: message. Instead, you send a display message; the display 
method (such as display, displayIfNeeded, or display:::) sees to it that the drawing context 
is properly set before initiating a drawSelf:: message to the View. 

The methods that respond to event messages (such as mouseUp:, keyDown:, and 
windowExposed:) also fall into this category. Event messages are initiated by the 
Application Kit when it receives events from the Window Server; you shouldn’t initiate 
them in your own code. 

The write: and read: methods for archiving and unarchiving are other examples of methods 
that shouldn’t be sent directly to objects. They’re generated by functions, such as 
NXWriteObjectO and NXReadObject(). 

If a method is designed to respond to messages generated by other methods or by a kit, the 
method description will generally say so. If there’s a penalty for generating the message 
within the code you write (as there is for drawSelf::), the description will include an 
explicit warning. 
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Common Classes 


A handful of classes come with the NeXT compiler for the Objective-C language. They 
include, most prominently, the Object class, which defines the basic functionality inherited 
by all objects. The Object class is at the root of all inheritance hierarchies. 

The other classes that come with the compiler are similar in that they also define 
functionality that can serve a wide variety of applications. They can be used with any kit. 
The five common classes are shown in Figure 2-1. 



Figure 2-1. Inheritance Hierarchy of the Common Classes 
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HashTable 


INHERITS FROM Object 

DECLARED IN objc/HashTable.h 

CLASS DESCRIPTION 

The HashTable class defines objects that store associations of keys and values. You use 
a HashTable object when you need a convenient and efficient way to store and access 
unordered data. Hash tables double as their number of associations increase, thus 
guaranteeing both constant average access time and linear size. 

HashTable objects are convenient to use, but when even greater efficiency of storage 
and access is required, consider using the C function interface to hash tables (see 
NXCreateHashTableO). Two alternatives to the HashTable class are NXStringTable 
and List. An NXStringTable is a HashTable that’s designed to store associations 
between keys and values that are both character strings. List is useful when you need 
to store a collection of objects; however, it doesn’t provide for storage of key/value 
pairs. Also, the time required to access an element in a List object grows linearly with 
the number of elements. 

In a HashTable object, keys and values can be of type id, int, void *, char *, or any 
other 32-bit quantity that can be described by a type string. The following outlines the 
usage of key and value descriptions: 

Hashing: A hash message is sent for object keys, a string hashing function is used for 
string keys, and a generic integer hashing function is used for all other cases. 

Equality: An isEqual: message is sent for object keys, and a string comparison is used 
for string keys. 

Descriptions must be invariant strings and are restricted to encode 32-bit quantities, 
typically the following: 

(id) “*” (char *) “i” (int) “!” (other) 

Two other restrictions that a HashTable must satisfy are: 

1. Keys must be invariant. In particular, when keys are strings, no copy is made, and 
the string is assumed to never change until the association is removed from the 
table. 

2. If two keys are equal in the sense of isEqual:, then their hashed values must be 
equal. If you’re creating a HashTable of List or Storage objects, note that these 
classes have an isEqual: method but no hash method; you can either subclass or 
define a hash method. 
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When freeing a HashTable, only object keys or object values are freed. Data is archived 
according to its type description. When description is hashing and equality are 
same as for On reading, however, the string is uniqued, using the 
NXUniqueStringQ function. 


INSTANCE VARIABLES 
Inherited from Object 
Declared in HashTable 


count 

keyDesc 


Class 


isa; 


unsigned 
const char 
const char 


count; 

*keyDesc; 

*valueDesc; 


Current number of associations 
Description of keys 


valueDesc 


Description of values 


METHOD TYPES 


Initializing and freeing a HashTable 

- init 

- initKeyDesc: 

- initKeyDesc:valueDesc: 

- initKeyDesc:valueDesc:capacity: 

- free 

- freeObjects 

- freeKeys lvalues: 

- empty 

Copying a HashTable - copy 

- copyFromZone: 

Manipulating table associations - count 

- isKey: 

- valueForKey: 

- insertKey:value: 

- removeKey: 


Iterating over all associations - initState 

- nextState:key:value: 

Archiving - read: 

- write: 
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INSTANCE METHODS 


copy 

-copy 

Returns a new HashTable. Keys nor values are copied. 

copyFromZone: 

- copyFromZone: 

Returns a new HashTable. Memory for the new HashTable is allocated from zone. 
Keys nor values are copied. 

count 

- (unsigned)count 

Returns the number of objects in the table. 

empty 

- empty 

Empties the HashTable but retains its capacity. 

free 

- free 

Deallocates the table, but not the objects that are in the table. 

freeKeys:values: 

- freeKeys:(void (*)(void *))keyFunc values:(void (*)(void *))valueFunc 

Conditionally deallocates the HashTable’s associations but does not deallocate the table 
itself. 

freeObjects 

- freeObjects 

Deallocates every object in the HashTable, but not the HashTable itself. Strings are not 
recovered. 
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init 


- init 


Initializes a new HashTable to map object keys to object values. Returns self. 

See also: - initKeyDesc:key:value:capacity: 

initKeyDesc: 

+ initKeyDesc: (const char *)aKeyDesc 

Initializes a new HashTable to map keys as described by aKeyDesc to object values. 
Returns self. 

See also: - initKeyDesc:key:value:capacity: 


initKeyDesc: valueDesc: 

- initKeyDesc: (const char *)aKeyDesc valueDesc: (const char *)aValueDesc 

Initializes a new HashTable to map keys and values as described by aKeyDesc and 
aValueDesc. Returns self. 

See also: - initKeyDesc:key:value:capacity: 

initKeyDesc:valueDesc:capacity: 

- initKeyDesc: (const char *)aKeyDesc 

valueDesc: (const char *)aValueDesc 
capacity: (xmsignQd)aCapacity 

Initializes a new HashTable. This is the designated initializer for HashTable objects: 
If you subclass HashTable, your subclass’s designated initializer must maintain the 
initializer chain by sending a message to super to invoke this method. See the 
introduction to the class specifications for more information. 

A HashTable initialized by this method maps keys and values as described by aKeyDesc 
and aValueDesc. aCapacity is given only as a hint; you can use 0 to create a table of 
minimal size. As more space is needed, it will be allocated automatically. Returns self. 

See also: - initKeyDesc:key:value:capacity: 
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initState 


- (NXHashState)initState 

Returns an NXHashState structure that’s required when iterating through the 
HashTable. Iterating through all associations of a HashTable involves setting up an 
iteration state, conceptually private to HashTable, and then progressing until all entries 
have been visited. An example of counting associations in a table follows: 


unsigned count = 0; 
const void *key; 

void *value; 

NXHashState state = [table initState]/ 

while ([table nextState: &state key: &key value: &value]) 
count++; 


See also: - nextState:key:value: 
insertKey:value: 

- (void *)insertKey:(const void *)aKey value:(void *)aValue 

Adds or updates a key and value pair, as specified by aKey and aValue. If aKey is 
already in the hash table, it’s associated with aValue and its previously associated value 
is returned. Otherwise, insertKey:value: returns nil. 

See also: - removeKey: 
isKey: 

- (BOOL)isKey: (const void *)aKey 

Returns YES if aKey is in the table, otherwise NO. 

See also: - valueForKey: 

nextState: key: value: 

- (BOOL)nextState: (NXHashState *)aState 

key:(const void **)aKey 
value:(void **)aValue 

Moves to the next entry in the HashTable and provides the addresses of pointers to its 
key/value pair. No insertKey: or removeKey: should be done while iterating through 
the table. Returns NO when there are no more entries in the table; otherwise, returns 
YES. 

See also: - initState 
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read: 

- read:(NXTypedStream *)stream 

Reads the HashTable from the typed stream stream. Returns self. 

See also: - write: 

removeKey: 

- (void *)removeKey:(const void *)aKey 

Removes the hash table entry identified by aKey. Always returns nil. 

See also: - insertKey:value: 

valueForKey: 

- (void *)valueForKey:(const void *)aKey 

Returns the value mapped to aKey. Returns nil if aKey is not in the table. 
See also: - isKey: 

write: 

- write:(NXTypedStream *)stream 

Writes the HashTable to the typed stream stream. Returns self. 

See also: -read: 
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INHERITS FROM 


Object 


DECLARED IN objc/List.h 

CLASS DESCRIPTION 

A List is a collection of objects. The class provides an interface that permits easy 
manipulation of the collection as a fixed or variable-sized list, a set, or an ordered 
collection. Lists are implemented as arrays to allow fast random access using an index. 
Indices start at 0. 

A List array contains object ids. An object isn’t copied when it’s added to a List; only 
its id is. There are no empty slots within the array, nil objects can’t be inserted in a 
List, and the collection is contracted to fill in the empty space when an object is 
removed. 

Lists grow dynamically when new objects are added. The default mechanism 
automatically doubles the capacity of the List when it becomes full, thus ensuring an 
average constant time for insertions, independent of the size of the List. 

For manipulating sets of structures that aren’t objects, see the Storage class. 


INSTANCE VARIABLES 
Inherited from Object 
Declared in List 


dataPtr 


numElements 

maxElements 


Class 

id 

unsigned int 
unsigned int 


isa; 

*dataPtr; 

numElements; 

maxElements; 


The data managed by the List object (the array of 
objects). 


The actual number of objects in the array. 

The total number of objects that can fit in 
currently allocated memory. 
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METHOD TYPES 


Initializing a new List object 

- init 

- initCount: 

Copying and freeing a List 

- copy 

- copyFromZone: 

-free 

Manipulating objects by index 

- insertObject:at: 

- addObject: 

- removeObjectAt: 

- removeLastObject 

- replaceObjectAt:with: 

- objectAt: 

- lastObject 

- count 

Manipulating objects by id 

- addObject: 

- addObjectlfAbsent: 

- removeObject: 

- replaceObject:with: 

- indexOf: 

Comparing Lists 

- isEqual: 

Emptying a List 

- empty 

- freeObjects 

Sending messages to the objects 

- makeObjectsPerform: 

- makeObjectsPerform:with: 

Managing the storage capacity 

- capacity 

- setAvailableCapacity: 

Archiving 

- read: 

- write: 


INSTANCE METHODS 

addObject: 

- addObject :anObject 

Inserts anObject at the end of the List, and returns self. However, if anObject is nil, 
nothing is inserted and nil is returned. 

See also: - insertObject:at: 
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addObjectlfAbsent: 

- addObiectlfAbsentianObject 

Inserts anObject at the end of the List and returns self, provided that anObject isn’t 
already in the List. If anObject is in the List, it won’t be inserted, but self is still 
returned. 

If anObject is nil, nothing is inserted and nil is returned. 

See also: - insertObject:at: 

capacity 

- (unsigned incapacity 

Returns the maximum number of objects that can be stored in the List without 
allocating more memory for it. When new memory is allocated, it’s taken from the 
same zone that was specified when the List was created. 

See also: - count, - setAvailableCapacity: 

copy 

-copy 

Returns a new List object with the same contents as the receiver. The objects in the List 
aren’t copied; therefore, both Lists contain pointers to the same set of objects. Memory 
for the new List is allocated from the same zone as the receiver. 

See also: - copyFromZone: 

copyFromZone: 

- copyFromZone :(NXZone *)zone 

Returns a new List object, allocated from zone , with the same contents as the receiver. 
The objects in the List aren’t copied; therefore, both Lists contain pointers to the same 
set of objects. 

See also: - copy 
count 

- (unsigned intjcount 

Returns the number of objects currently in the List. 

See also: - capacity 
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empty 
- empty 

Empties the List of all its objects without freeing them, and returns self. The current 
capacity of the List isn’t changed. 

See also: -freeObjects 


free 

-free 

Deallocates the List object and the memory it allocated for the array of object ids. 
However, the objects themselves aren’t freed. 

See also: - freeObjects 

freeObjects 

- freeObjects 

Removes every object from the List, sends each one of them a free message, and returns 
self. The List object itself isn’t freed and its current capacity isn’t altered. 

The methods that free the objects shouldn’t have the side effect of modifying the List. 

See also: - empty 

indexOf: 

- (unsigned intjindexOf lanObject 

Returns the index of the first occurrence of anObject in the List, or 
NX_NOT_IN_LIST if anObject isn’t in the List. 


init 


- init 


Initializes the receiver, a new List object, but doesn’t allocate any memory for its array 
of object ids. It’s initial capacity will be 0. Minimal amounts of memory will be 
allocated when objects are added to the List. Or an initial capacity can be set, before 
objects are added, using the setAvailableCapacity: method. Returns self. 

See also: - initCount:, - setAvailableCapacity: 
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initCount: 


- initCount: (unsigned int )numSlots 

Initializes the receiver, a new List object, by allocating enough memory for it to hold 
numSlots objects. Returns self. 

This method is the designated initializer for the class. It should be used immediately 
after memory for the List has been allocated and before any objects have been assigned 
to it; it shouldn’t be used to reinitialize a List that’s already in use. 

See also: -capacity 
insertObject:at: 

- msertObfect'.anObject at: (unsigned mi)index 

Inserts anObject into the List at index, moving objects down one slot to make room. If 
index equals the value returned by the count method, anObject is inserted at the end of 
the List. However, the insertion fails if index is greater than the value returned by count 
or anObject is nil. 

If anObject is successfully inserted into the List, this method returns self. If not, it 
returns nil. 

See also: - count, - addObject: 
isEqual: 

- (BOOL)isEqual:tf«0fo/£ct 

Compares the receiving List to anObject. If anObject is a List with exactly the same 
contents as the receiver, this method returns YES. If not, it returns NO. 

Two Lists have the same contents if they each hold the same number of objects and the 
ids in each List are identical and occur in the same order. 

lastObject 

- lastObject 

Returns the last object in the List, or nil if there are no objects in the List. This method 
doesn’t remove the object that’s returned. 

See also: - removeLastObject 
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makeObjectsPerform: 

- makeObjectsPerform:(SEL)< 2 SW£ctor 

Sends an aSelector message to each object in the List in reverse order (starting with the 
last object and continuing backwards through the List to the first object), and returns 
self. The aSelector method must be one that takes no arguments. It shouldn’t have the 
side effect of modifying the List. 

makeObjectsPerform:with: 

- makeObjectsPerform :{$EL)aS elector with lanObject 

Sends an aSelector message to each object in the List in reverse order (starting with the 
last object and continuing backwards through the List to the first object), and returns 
self. The message is sent each time with anObject as an argument, so the aSelector 
method must be one that takes a single argument of type id. The aSelector method 
shouldn’t, as a side effect, modify the List. 

objectAt: 

- objectAt: (unsigned int )index 

Returns the id of the object located at slot index, or nil if index is beyond the end of the 
List. 

See also: - count 

read: 

- read:(NXTypedStream *)stream 

Reads the List and all the objects it contains from the typed stream stream . 

See also: - write: 

removeLastObject 

- removeLastObject 

Removes the object occupying the last position in the List and returns it. If there are 
no objects in the List, this method returns nil. 

See also: - lastObject, - removeObjectAt: 
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removeObject: 

- remo\eOb\ect:anObject 

Removes the first occurrence of anObject from the List, and returns it. If anObject isn’t 
in the List, this method returns nil. 

The positions of the remaining objects in the List are adjusted so there’s no gap. 

See also: - removeLastObject, - removeObjectAt: 

removeObjectAt: 

- removeObjectAt: (unsigned int )index 

Removes the object located at index and returns it. If there’s no object at index, this 
method returns nil. 

The positions of the remaining objects in the List are adjusted so there’s no gap. 

See also: - removeLastObject, - removeObject: 

replaceObjectrwith: 

- rep\aceOb}ect:anObject with inewObject 

Replaces the first occurrence of anObject in the List with newObject, and returns 
anObject. However, if newObject is nil or anObject isn’t in the List, nothing is replaced 
and nil is returned. 

See also: - replaceObjectAt:with: 
replaceObjectAtrwith: 

- replaceObject At: (unsigned int )index with inewObject 

Returns the object at index after replacing it with newObject. If there’s no object at 
index or newObject is nil, nothing is replaced and nil is returned. 

See also: - replaceObject:with: 
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set AvailableCapacity: 

- set AvailableCapacity: (unsigned mt)numSlots 

Sets the storage capacity of the List to at least numSlots objects and returns self. 
However, if the List already contains more than numSlots objects (if the count method 
returns a number greater than numSlots ), its capacity is left unchanged and nil is 
returned. 

See also: - capacity, - count 
write: 

- write :(NXTypedStream *)stream 

Writes the List, including all the objects it contains, to the typed stream stream. 

See also: - read: 
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NXStringTable 


INHERITS FROM HashTable : Object 

DECLARED IN objc/NXStringTable.h 

CLASS DESCRIPTION 

NXStringTable defines an object that associates a key with a value. Both the key and 
the value must be character strings. For example, these keys and values might be 
associated in a particular NXStringTable: 


Key 

Value 

"Yes" 

"Oui" 

"No" 

"Non" 


By using an NXStringTable object to store your application’s character strings, you can 
reduce the effort required to adapt the application to different language markets. 
Interface Builder give you direct access to NXStringTables, letting you create and 
initialize a string table and connect it into your application. 

A new NXStringTable instance can be created either through Interface Builder’s 
Classes window or through the inherited alloc... and init... methods. Similarly, you can 
establish the contents of an NXStringTable either directly through Interface Builder or 
programmatically through NXStringTable methods that read keys and values that are 
stored in a file (see readFromFile: and readFromStream:). Each assignment in the 
file can be of either of these formats: 


"key" = "value"; 

"key"; 

If only key is present for a particular assignment, the corresponding value is taken to be 
identical to key. 

A valid key or value—a valid token—is composed of text enclosed in double quotes. 
The text can’t include double quotes or the null character. It can include the escape 
sequences: \a, \b, \f, \n, \r, \l, \v, and \". The backslash is stripped for any other 
character; consequently, numeric escape codes aren’t interpreted. White space between 
tokens is ignored. A key or value can’t exceed MAX_NXSTRINGTABLE_LENGTH 
characters. 

The file can also include standard C-language comments which the NXStringTable 
ignores. However, these comments can provide valuable information for a person 
who’s translating or documenting the application. 
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To retrieve the value associated with a specific key, send a valueForStringKey: 
message to the NXStringTable. For example, assuming myStringTable is an 
NXStringTable containing the appropriate keys and values, this call would display an 
attention panel announcing a problem opening a file: 


NXRunAlertPanel([myStringTable valueForStringKey:"openTitle"], 
[myStringTable valueForStringKey:"openError"], 

"OK", 

NULL, 

NULL); 

If you’re accessing NXStringTables through Interface Builder, please note the 
following. For efficiency, use several NXStringTables—each in its own interface file— 
rather than one large one. By using several NXStringTables, your application can load 
only those strings that it needs at a particular time. For example, you might place all 
the strings associated with a help system in an NXStringTable in one interface file and 
those associated with error messages in another NXStringTable in another file. When 
the user accesses the help system for the first time, the application can load the 
appropriate NXStringTable. Also, instantiate only one copy of any individual 
NXStringTable. Don’t put an NXStringTable object in an interface file that will be 
loaded more than once, since multiple copies of the same table will result. 


INSTANCE VARIABLES 



Inherited from Object 

Class 

isa; 

Inherited from HashTable 

unsigned 

count; 


const char 

*keyDesc; 


const char 

*valueDesc; 

Declared in NXStringTable 

(none) 



METHOD TYPES 


Initializing and freeing an NXStringTable 

- init 

- free 

Querying an NXStringTable - valueForStringKey: 


Reading and writing elements - readFromFile: 

- writeToFile: 

- readFromStream: 

- writeToStream: 
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INSTANCE METHODS 


free 
- free 

Frees the string table and its strings. You should never send a freeObjects (HashTable) 
message to an NXStringTable. 


init 


- init 


Initializes a new NXStringTable. This is the designated initializer for the 
NXStringTable class. Returns self. 

readFromFile: 

- readFromFile: (const char *)fileName 

Reads an ASCII representation of the NXStringTable’s keys and values from fileName. 
The NXStringTable opens a stream on the file and then sends itself a 
readFromStream: message to load the data. See “Class Description” above for the 
format of the data. Returns nil on error; otherwise, returns self. 

See also: - readFromStream: 

readFromStream: 

- readFromStream:(NXStream *)stream 

Reads an ASCII representation of the NXStringTable’s keys and values from stream . 
See “Class Description” above for the format of the data. Returns nil on error; 
otherwise, returns self. 

See also: - readFromFile: 
valueFor Str ingKey: 

- (const char *)valueForStringKey:(const char *)aString 

Searches the string table for the value that corresponds to the key aString. Returns 
NULL if and only if no value is found for that key; otherwise, returns a pointer to the 
value. 
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writeToFile: 


- writeToFile:(const char *)fileName 

Writes an ASCII representation of the NXStringTable’s keys and values to fileName. 
The NXStringTable opens a stream on the file and then sends itself a writeToStream: 
message. See “Class Description” above for the format of the data. Returns nil if an 
error occurs; otherwise, returns self. 

See also: - writeToStream: 
writeToStream: 

- writeToStream :(NXStream *)stream 

Writes an ASCII representation of the NXStringTable’s keys and values to stream. See 
“Class Description” above for the format of the data. Returns self. 

See also: - writeToFile: 

CONSTANTS AND DEFINED TYPES 

#define MAX NXSTRINGTABLE LENGTH 1024 
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Object 


INHERITS FROM none (Object is the root class.) 

DECLARED IN objc/Object.h 

CLASS DESCRIPTION 

Object is an abstract superclass that defines a basic interface to the Objective-C 
run-time system that other classes use and build upon. It’s the root of all Objective-C 
inheritance hierarchies, the only class that has no superclass. All other classes inherit 
from Object. 

Among other things, the Object class provides its subclasses with a framework for 
creating, initializing, freeing, copying, comparing, and archiving objects, for 
performing methods selected at run-time, for querying an object about its methods and 
its position in the inheritance hierarchy, and for forwarding messages to other objects. 
For example, to query an object about what class it belongs to, you’d send it a class or 
a name message. To find out whether it implements a particular method, you’d send it 
a respondsTo: message. 

This type of information is obtained through the object’s isa instance variable, which 
points to a class structure that describes the object to the run-time system. Because all 
objects directly or indirectly inherit from the Object class, they all have this variable. 
The installation of the class structure (the initialization of isa) is one of the 
responsibilities of the alloc, allocFromZone:, and new methods, the same methods 
that create (allocate memory for) new instances of a class. The defining characteristic 
of an “object” is that its first instance variable is an isa pointer to a class structure. 


INSTANCE VARIABLES 
Declared in Object 
isa 


Class isa; 

A pointer to the instance’s class structure. 


METHOD TYPES 

Initializing the class + initialize 
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Creating, copying, and freeing instances 

+ alloc 

+ allocFromZone: 

+ new 

- copy 

- copyFromZone: 

- zone 

- free 
+ free 

Initializing a new instance - init 

Identifying classes - class 

+ class 

- name 

- superclass 
+ superclass 

Identifying and comparing instances 

- hash 

- isEqual: 

- self 

Testing inheritance relationships - isKindOf: 

- isKindOfGivenName: 

- isMemberOf: 

- isMemberOfGivenName: 

Testing class functionality + instancesRespondTo: 

- respondsTo: 


Sending messages determined at run time 



- perform: 

- perform:with: 

- perform: with:with: 

Forwarding messages 

- forward:: 

-performv:: 

Obtaining method handles 

+ instanceMethodFor: 

- methodFor: 

Posing 

+ pose As: 

Enforcing intentions 

- notlmplemented: 

- subclassResponsibility: 

Error handling 

- doesNotRecognize: 

- error: 
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Dynamic loading 
Archiving 


CLASS METHODS 

alloc 
+ alloc 

Returns a new instance of the receiving class. The isa instance variable of the new 
object is initialized to a data structure that describes the class; otherwise the object isn’t 
initialized. A version of the init method should be used to complete the initialization 
process. For example: 

id newObject = [[TheClass alloc] init]; 

Subclasses shouldn’t override alloc to add code that initializes the new instance. 
Instead, class-specific versions of the init method should be implemented for that 
purpose. Versions of the new method can also be implemented to combine allocation 
and initialization. 

Note: The alloc method doesn’t invoke allocFromZone:. The two methods work 
independently. 

See also: + allocFromZone:, - init, + new 
allocFromZone 

+ allocFromZone :(NXZone *)zone 

Returns a new instance of the receiving class. The isa instance variable of the new 
object is initialized to a data structure that describes the class; its other instance 
variables aren’t initialized. Memory for the new object is allocated from zone. 

This method is always used in conjunction with an init method that completes the 
initialization of the new instance. For example: 

id newObject = [[TheClass allocFromZone:someZone] init]; 


+ fimshLoadmg: 

+ startUnloading 

- read: 

- write: 

- startArchiving: 

- awake 

- finishUnarchiving 
+ set Version: 

+ version 
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The allocFromZone: method shouldn’t be overridden to include any initialization 
code. Instead, class-specific versions of the init method should be implemented for tha 
purpose. 

When one object creates another, it’s often a good idea to make sure they’re both 
allocated from the same region of memory. The zone method can be used for this 
purpose; it returns the zone where the receiver is located. For example: 


id myCompanion = [[TheClass allocFromZone:[self zone]] init]; 

See also: + alloc, - zone, - init 

class 
+ class 

Returns self. Since this is a class method, it returns the class object. 

See also: - name, - class 

finishLoading: 

+ finishLoading: (struct maeh_header *)header 

Implemented by subclasses to integrate a newly loaded class or category into a runnini 
program. A finishLoading: message is sent to the class object immediately after the 
class, or a category of the class, has been dynamically loaded—if the newly loaded 
class or category implements a method that can respond, header is a pointer to the 
structure that describes the modules that were just loaded. 

Once a dynamically loaded class is used, it will also receive an initialize message. 
However, because the finishLoading: message is sent immediately after the class is 
loaded, it always precedes the initialize message, which is sent only when the class 
receives its first message from the program. 

A finishLoading: method is specific to the class or category where it’s defined, and 
isn’t inherited by subclasses or shared with the rest of the class. Thus a class that ha: 
four categories can define a total of five finishLoading: methods, one in each categor 
and one in the main class definition. The method that’s performed is the one defined ii 
the class or category just loaded. 

There’s no default finishLoading: method. The Object class declares a protocol for 
this method, but doesn’t implement it. 

See also: + startUnloading 
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free 


+ free 

Returns nil. This method is implemented to prevent class objects, which are “owned” 
by the Objective-C run-time system, from being accidentally freed. To free an instance, 
use the instance method free. 

See also: - free 

initialize 
+ initialize 

Initializes the class before it’s used (before it receives its first message). The 
Objective-C run-time system generates an initialize message to each class just before 
the class, or any class that inherits from it, is sent its first message from within the 
program. Each class object receives the initialize message just once. Superclasses 
receive it before subclasses do. 

For example, if the first message your program sends is this, 


[Application alloc] 


the run-time system will generate these three initialize messages, 

[Object initialize]; 

[Responder initialize]; 

[Application initialize]; 


since Application is a subclass of Responder and Responder is a subclass of Object. All 
the initialize messages precede the alloc message and are sent in the order of 
inheritance, as shown. 

If your program later begins to use the Text class, 


[Text instancesRespondTo:someSelector] 


the run-time system will generate these initialize messages, 


[View initialize]; 
[Text initialize]; 


since the Text class inherits from Object, Responder, and View. The 
instancesRespondTo: message is sent only after all these classes are initialized. Note 
that the initialize messages to Object and Responder aren’t repeated; each class is 
initialized only once. 

You can implement your own versions of initialize to provide class-specific 
initialization as needed. 
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Because initialize methods are inherited, it’s possible for the same method to be 
invoked many times, once for the class that defines it and once for each inheriting class. 
To prevent code from being repeated each time the method is invoked, it can be 
bracketed as shown in the example below: 

+ initialize 
{ 

if ( self == [MyClass class] ) { 

/* put initialization code here */ 

} 

return self; 

} 

See also: - init, - class 

instanceMethodFor: 

+ (IMP)instanceMethodFor :(SEL)a SWector 

Locates and returns the address of the implementation of the aSelector instance 
method. An error is generated if instances of the receiver can’t respond to aSelector 
messages. 

This method, and the function pointer that it returns, are subject to the same constraints 
as those described for the instance method methodFor:. 

See also: - methodFor: 

instancesRespondTo: 

+ (BOOL)instancesRespondTo:(SEL)«5c/cctor 

Returns YES if instances of the class are capable of responding to aSelector messages, 
and NO if they’re not. The application is responsible for determining whether a NO 
response should be considered an error. 

If an instance can successfully forward aSelector messages to other objects, it will be 
able to receive the message without error even though instancesRespondTo: returns 
NO. 

See also: - respondsTo: 
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new 


+ new 

Creates a new instance of the receiving class, sends it an init message, and returns the 
initialized object returned by init. 

As defined in the Object class, new is essentially a combination of alloc and init. Like 
alloc, it initializes the isa instance variable of the new object so that it points to the class 
data structure; it leaves the initialization of other instance variables up to the init 
method. 

Unlike alloc, new is sometimes reimplemented in subclasses to have it invoke a 
class-specific initialization method. If the init method includes arguments, they’re 
typically reflected in the new method. For example: 

+ newArg:(int)tag arg:(struct info *)data 
{ 

return [[self alloc] initArg:tag arg:data]; 

} 

However, there’s little point in implementing new... methods if they’re simply 
shorthand for alloc and init..., like the one shown above. Often new... methods will do 
more than just allocation and initialization. In some classes, they manage a set of 
instances, returning the one with the requested properties if it already exists, allocating 
and initializing a new one only if necessary. For example: 

+ newArg: (int)tag arg: (struct info *)data 
{ 

id thelnstance; 

if ( thelnstance = findTheObjectWithTheTag(tag) ) 
return thelnstance; 

return [[self alloc] initArg:tag arg:data]; 

} 

Although it’s appropriate to define new new... methods in this way, the alloc and 
allocFromZone: methods should never be augmented to include initialization code. 

See also: - init, + alloc, + allocFromZone: 
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pose As: 

+ pose AsiaClassObject 

Permits the receiver to “pose as” the aClassObject class. All messages to aClassObject 
will actually be sent to the receiver. The receiver should be defined as a subclass of 
aClassObject and shouldn’t declare any instance variables of its own. A poseAs: 
message should be sent before any instances of aClassObject are created. 

This facility allows you to add methods to an existing class by defining them in a 
subclass and having the subclass pose as the existing class. The new method definitions 
will be inherited by all subclasses of the existing class. Care should be taken to ensure 
that this doesn’t generate errors. 

Posing is useful as a debugging tool, but category definitions are a less complicated and 
more efficient way of augmenting existing classes. 

Posing has only one feature that categories lack: The methods added by a posing class 
can override methods already defined for the existing class. You can therefore use 
posing to replace existing methods with new versions. 

Returns self. 

set Version: 

+ setVersion:(int)<2Vfer.s7<9« 

Sets the class version number to aVersion, and returns self. The version number is 
helpful when instances of the class are to be archived and reused later. 

See also: + version 

startUnloading 
+ startUnloading 

Implemented by subclasses to prepare for the class or category being unloaded from a 
running program. A startUnloading message is sent to the class object immediately 
before the class, or category of the class, is unloaded—if a method that can respond is 
implemented in the class or category about to be unloaded. 

A startUnloading method is specific only to the class or category where it’s defined, 
and isn’t inherited by subclasses or shared with the rest of the class. Thus a class that 
has four categories can define a total of five startUnloading methods, one in each 
category and one in the main class definition. The method that’s performed is the one 
defined in the class or category that will be unloaded. 

There’s no default startUnloading method. The object class declares a protocol for 
this method but doesn’t implement it. 

See also: + finishLoading: 
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superclass 

+ superclass 

Returns the class object for the receiver’s superclass. 

See also: + class, - superclass 

version 

+ (int)version 

Returns the version number assigned to the class. If no version has been set, this will 
be 0. 

See also: + setVersion: 


INSTANCE METHODS 

awake 
- awake 

Implemented by subclasses to reinitialize the receiving object after it has been 
unarchived (by read:). An awake message is automatically sent to every object after 
it has been unarchived and after all the objects it refers to are in a usable state. 

The default version of the method defined here merely returns self. 

You can implement an awake method in any class to provide for more initialization 
than can be done in the read: method. Each implementation of awake should limit the 
work it does to the scope of the class definition, and incorporate the initialization of 
classes farther up the inheritance hierarchy through a message to super. For example: 


- awake 
{ 

[super awake]/ 

/* class-specific initialization goes here */ 
return self; 

} 


All implementations of awake should return self. 
See also: - read:, - finishUnarchiving 
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class 


- class 

Returns the class object for the receiver s class. 
See also: + class 


copy 

-copy 

Returns a new instance that s an exact copy of the receiver. This method creates only 
one new object. If the receiver has instance variables that point to other objects, the 
instance variables in the copy will point to the same objects. The values of the instance 
variables are copied, but the objects they point to aren t. 

See also: - copyFromZone: 

copyFromZone: 

- copyFromZone :(NXZone *)zone 

Returns a new instance that s an exact copy of the receiver. Memory for the new 
instance is allocated from zone. This method creates only one new object; it works 
exactly like the copy method, except that it allows you to determine where the copy will 
reside in memory. 

See also: -copy,-zone 


doesNotRecognize: 

- doesNotRecognize :(SEL)aSelector 

Handles aSelector messages that the receiver doesn t recognize. The Objective-C 
run-time system invokes this method whenever an object receives an aSelector message 
that it can t respond to or forward. It, in turn, invokes the error: method to generate an 
error message and abort the current process. 

doesNotRecognize: messages should be sent only by the run-time system. Although 
they re sometimes used in program code to prevent a method from being inherited, it s 
better to use the error: method directly. For example, an Object subclass might 
renounce the copy method by reimplementing it to include an error: message as 
follows: 


- copy 
{ 


} 


[self error:" 

[self 


%s objects should not be sent 
name], sel_getName(_cmd)]; 


%s messages\n", 
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This code prevents instances of the subclass from recognizing or forwarding copy 
messages although the respondsTo: method will still report that the receiver has 
access to a copy method. 

(The _cmd variable identifies to the current selector; in the example above, it identifies 
the selector for the copy method. The sel_getName() function returns the method 
name corresponding to a selector code; in the example, it returns the name copy .) 

See also: - error:, - subclassResponsibility:, - name 

error: 

- error:(ST RjaString ,... 

Generates a formatted error message, in the manner of printf(), from aString followed 
by a variable number of arguments. For example: 

[self error:"index %d exceeds limit %d\n", index, limit]; 

The message specified by aString is preceded by this standard prefix (where <class> 
is the name of the receiver s class): 


"error: <class> " 


This method doesn t return. After generating the error message, it calls abort() to 
create a core file and terminate the process. It works through the Objective-C run-time 
_error function. 

See also: - subclassResponsibility:, - notlmplemented:, - doesNotRecognize: 

finishUnarchiving 
- finishUnarchiving 

Implemented by subclasses to replace an unarchived object with a new object if 
necessary. A finishUnarchiving message is sent to every object after it has been 
unarchived (using read:) and initialized (by awake), but only if a method has been 
implemented that can respond to the message. 

The finishUnarchiving message gives the application an opportunity to test an 
unarchived and initialized object to see whether it s usable, and, if not, to replace it with 
another object that is. This method should return nil if the unarchived instance (self) is 
OK; otherwise, it should free the receiver and return another object to take its place. 

There s no default implementation of the finishUnarchiving method. The Object class 
declares this method, but doesn t define it. 

See also: - read:, - awake, - start Archiving: 
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forward:: 


- forward: (SEL)aSelector : (mzrg_\isi)argFrame 

Implemented by subclasses to forward messages to other objects. When an object is 
sent an aSelector message, and the run-time system can’t find an implementation of the 
method for the receiving object, it sends the object a forward:: message to give it an 
opportunity to delegate the message to another object. (If that object can’t respond to 
the message either, it too will be given a chance to forward it.) 

The forward:: message thus allows an object to establish relationships with other 
objects that will, for certain messages, act on its behalf. The forwarding object is, in a 
sense, able to “inherit” some of the characteristics of the object it forwards the message 
to. 

A forward:: message is generated only if the aSelector method isn’t implemented by 
the receiving object’s class or by any of the classes it inherits from. 

An implementation of the forward:: method can do more than just forward messages. 
It can, for example, locate code that responds to a variety of different messages, thus 
avoiding the necessity of having to write a separate method for each selector. A 
forward:: method might also involve several other objects in the response to a 
message, rather than forward it to just one. 

If implemented to forward messages, a forward:: method has two tasks: 

• To locate an object that can respond to the aSelector message. This need not be the 
same object for all messages. 

• To send the message to that object, using the performv:: method. 

In the simple case, in which an object forwards messages to just one destination (such 
as the hypothetical friend instance variable in the example below), a forward: : method 
could be as simple as this: 

- forward:(SEL)aSelector :(marg_list)argFrame 
{ 

if ( [friend respondsTo:aSelector] ) 

return [friend performv:aSelector :argFrame]; 
return [self doesNotRecognize:aSelector]; 

} 

argFrame is a pointer to the arguments included in the original aSelector message. It’s 
passed directly to performv:: without change. 

The default version of forward:: implemented in the Object class simply invokes the 
doesNotRecognize: method. It doesn’t forward messages. Thus if you choose not to 
implement forward:: methods, unrecognized messages will be handled in the usual 
way. 

See also: - performv::, - doesNotRecognize: 
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free 


- free 

Frees the memory occupied by the receiver and returns nil. This method also sets the 
isa pointer of the freed object to nil, so that subsequent messages to the object will 
generate an error indicating that a message was sent to a freed object. 

This method uses object_deallocate() to free the receiver’s memory. 

hash 

- (unsigned intjhash 

Returns an unsigned integer that’s guaranteed to be the same for any two objects which 
are equal according to the isEqual: method. The integer is derived from the id of the 
receiver. 

See also: - isEqual: 


init 


- init 


Implemented by subclasses to initialize a new object (the receiver) immediately after 
memory for it has been allocated. An init message is generally coupled with an alloc 
or allocFromZone: message in the same line of code: 


id newObject = [ [TheClass alloc] init]; 


Subclass versions of this method should return the new object (self) if it has been 
successfully initialized. If it can’t be initialized, they should free the object and return 
nil. The version of the method defined here simply returns self. 

Every class must guarantee that the init method returns a fully functional instance of 
the class. This typically means overriding the method to add class-specific 
initialization code. Subclass versions of the method need to incorporate the 
initialization code for the classes they inherit from, through a message to super: 


- init 
{ 

[super init]; 

/* class-specific initialization goes here */ 
return self; 

} 


Note that the message to super precedes the initialization code added in the method. 
This ensures that initialization proceeds in the order of inheritance. 
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Subclasses often add arguments to the init method to allow specific values to be set. 
The more arguments a method has, the more freedom it gives you to determine the 
character of initialized objects. Classes often have a set of init... methods, each with a 
different number of arguments. For example: 

- init; 

- initArg:(int)tag; 

- initArg:(int)tag arg:(struct info *)data; 


The convention is that at least one of these methods, usually the one with the most 
arguments, includes a message to super to incorporate the initialization of classes 
higher up the hierarchy. This method is the designated initializer for the class. The 
other init... methods defined in the class directly or indirectly invoke the designated 
initializer through messages to self. In this way, all init... methods are chained together. 
For example: 


- init 
{ 

return [self initArg:-l]; 

} 

- initArg:(int)tag 
{ 

return [self initArg:tag arg:NULL]; 

} 

- initArg:(int)tag arg:(struct info *)data 
{ 

[super init. . .]; 

/* class-specific initialization goes here */ 

} 

In this example, the initArg:arg: method is the designated initializer for the class. 

If a subclass does any initialization of its own, it must define its own designated 
initializer. This method should begin by sending a message to super to perform the 
designated initializer of its superclass. Suppose, for example, that the three methods 
illustrated above are defined in the B class. The C class, a subclass of B, might have 
this designated initializer: 

- initArg:(int)tag arg:(struct info *)data arg:anObject 
{ 

[super initArg:tag argidataj; 

/* class-specific initialization goes here */ 

} 

If inherited init... methods are to successfully initialize instances of the subclass, they 
must all be made to (directly or indirectly) invoke the new designated initializer. To 
accomplish this, the subclass is obliged to cover (override) only the designated 
initializer of the superclass. For example, in addition to its designated initializer, the C 
class would also implement this method: 
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- initArg:(int)tag arg:(struct info *)data 
{ 

return [self initArgrtag arg:data arginil]; 

} 

This ensures that all three methods inherited from the B class also work for instances 
of the C class. 

Often the designated initializer of the subclass overrides the designated initializer of the 
superclass. If so, the subclass need only implement the one init... method. 

These conventions maintain a direct chain of init... links, and ensure that the new 
method and all inherited init... methods return usable, initialized objects. They also 
prevent the possibility of an infinite loop wherein a subclass method sends a message 
(to super) to perform a superclass method, which in turn sends a message (to self) to 
perform the subclass method. 

The Object class also has a designated initializer—this init method. Subclasses that do 
their own initialization should override it, as described above. 

See also: + new, + alloc, + allocFromZone: 
isEqual: 

- (BOOL)isEqual lanObject 

Returns YES if the receiver is the same as anObject, and NO if it isn’t. This is 
determined by comparing the id of the receiver to the id of anObject. 

The hash method is guaranteed to return the same integer for both objects when this 
method returns YES. 

See also: hash 

isKindOf: 

- (BOOL)isKindOf :aClassObject 

Returns YES if the receiver is an instance of aClassObject or an instance of any class 
that inherits from aClassObject. Otherwise, it returns NO. For example, in this code 
isKindOf: would return YES: 

id aMenu = [[Menu alloc] init]; 

if ( [aMenu isKindOf:[Window class]] ) 


In the Application Kit, the Menu class inherits from Window. 
See also: - isMemberOf: 
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isKindOfGivenName: 


- (BOOL)isKindOfGivenName:(STR)<2C/assAfame 

Returns YES if the receiver is an instance of aClassName or an instance of any class 
that inherits from aClassName. This method is the same as isKindOf:, except it takes 
the class name, rather than the class id, as its argument. 

STR is defined, in objc/objc.h, as a character pointer (char *). 

See also: - isMemberOfGivenName: 

isMemberOf: 

- (BOOL)isMemberOf:<zC/<2.s\sOZ?/£cf 

Returns YES if the receiver is an instance of aClassObject. Otherwise, it returns NO. 
For example, in this code, isMemberOf: would return NO: 

id aMenu = [[Menu alloc] init]; 
if ([aMenu isMemberOf:[Window class]]) 


See also: - isKindOf: 

isMemberOfGivenName: 

- (BOOL)isMemberOfGivenName:(STR)flC/<mAfara<? 

Returns YES if the receiver is an instance of aClassName, and NO if it isn’t. This 
method is the same as isMemberOf:, except it takes the class name, rather than the 
class id, as its argument. 

STR is defined, in objc/objc.h, as a character pointer (char *). 

See also: - isKindOfGivenName: 

methodFor: 

- (IMP)methodFor:(SEL)aSe/ector 

Locates and returns the address of the receiver’s implementation of the aSelector 
method. An error is generated if the receiver has no implementation of the method (if 
it can’t respond to aSelector messages). 

IMP is defined (in the objc/objc.h header file) as a pointer to a function that takes a 
variable number of arguments and returns an id. It’s the only prototype provided for 
the function pointer that methodFor: returns. Therefore, if the aSelector method takes 
any arguments or returns anything but an id, its function counterpart will be 
inadequately prototyped. Lacking a prototype, the compiler will promote floats to 
doubles and chars to ints, which the implementation won’t expect. It will therefore 
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behave differently (and erroneously) when called as a function than when performed as 
a method. 

To remedy this situation, it’s necessary to provide your own prototype. In the example 
below, IMPEqual is used to prototype the implementation of the isEqual: method. It’s 
defined as pointer to a function that returns a BOOL and takes an id in addition to the 
two “hidden” arguments (self, the current receiver, and _cmd, the current selector) that 
are passed to every method implementation. 

typedef BOOL (*IMPEqual)(id, SEL, id); 

IMPEqual tester; 

tester = (IMPEqual)[target methodFor:@selector(isEqual:)]; 
while ( !tester(target, ^selector(isEqual:), someObject) ) { 

} 

Note that turning a method into a function by obtaining the address of its 
implementation “unhides” the self and _cmd arguments. 

See also: + instanceMethodFor: 

name 

- (const char *)name 

Returns a character string with the name of the receiver’s class. This information is 
often used in error messages or debugging statements. 

See also: + class 

notlmplemented: 

- notlmplemented :(SEL)aSelector 

Used in the body of a method definition to indicate that the programmer intended to 
implement the method, but left it as a stub for the time being. aSelector is the selector 
for the unimplemented method; notlmplemented: messages are sent to self. For 
example: 

- methodNeeded 
{ 

[self notImplemented:_cmd]; 

} 

When a methodNeeded message is received, notlmplemented: will invoke the error: 
method to generate an appropriate error message and abort the process. (In this 
example, _cmd refers to the methodNeeded selector.) 

See also: - subclassResponsibility:, - error: 
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perform: 

- perform:(SEL )aSelector 


Sends an aSelector message to the receiver and returns the result of the message. This 
allows you to send messages that aren’t determined until run time. For example, all 
three of the following messages do the same thing: 


id myClone 
id myClone 
id myClone 


[anObject 
[anObject 
[anObject 


copy]; 

perform:@selector(copy)]; 
perform:sel_getUid("copy") 


aSelector should identify a method that takes no arguments. If the method returns 
anything but an object, the return must be cast to the correct type. For example: 


char *myClass; 

myClass = (char *)[anObject perform:©selector(name)]; 

Casting works for any integral type (char, short, int, long, or enum) or any pointer. 
However, it doesn’t work if the return is a floating type (float or double) or a structure 
or union. This is because the C language doesn’t permit a pointer (like id) to be cast to 
these types. 

Therefore, perform: shouldn’t be asked to perform any method that returns a floating 
type, structure, or union. An alternative is to get the address of the method 
implementation (using methodFor:) and call it as a function. For example: 


float grayValue; 

grayValue = ((float (*)())[anObject methodFor:©selector(gray)])(); 

See also: - performrwith:, - perform:with:with:, - methodFor: 
perform:with: 

- perform: (SEL)aSelector withianObject 

Sends an aSelector message to the receiver with anObject as an argument. This method 
is the same as perform:, except that you can supply an argument for the aSelector 
message. aSelector should identify a method that takes a single argument of type id. 

See also: - perform: 
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perform: with: with: 

- perform: (SEL)aSelector 

with: objectl 
with :object2 

Sends the receiver an aSelector message with objectl and object2 as arguments. This 
method is the same as perform:, except that you can supply two arguments for the 
aSelector message. aSelector should identify a method that can take the two arguments 
of type id. 

See also: - perform: 
performv:: 

- performv:(SEL)tfSdector :(maig_list)argFrame 

Sends the receiver an aSelector message with the arguments in argFrame. performv:: 
messages are used within implementations of the forward:: method. Both arguments, 
aSelector and argFrame, are identical to the arguments the run-time system passes to 
forward::. They can be taken directly from that method and passed through without 
change to performv::. 

performv:: should be restricted to implementations of the forward:: method. 
Although it may seem like a more flexible way of sending messages than perform:, 
perform:with:, or perform:with:with:, in that it doesn’t restrict the number of 
arguments in the aSelector message or their type, it’s not an appropriate substitute for 
those methods. First, it’s more expensive than they are. The run-time system must 
parse the arguments in argFrame based on information stored for aSelector. Second, 
in future releases performv:: may not work in contexts other than the forward:: 
method. 

See also: - forward::, - perform: 
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read: 


- read:(NXTypedStream *) stream 

Implemented by subclasses to read the receiver’s instance variables from the typed 
stream stream. You need to implement a read: method for any class you create, if you 
want its instances (or instance of classes that inherit from it) to be archivable. 

The method you implement should unarchive the instance variables defined in the class 
in a manner that matches they way they were archived by write:. In each class, the 
read: method should begin with a message to super: 

- read:(NXTypedStream *)stream 
{ 

[super read:stream]; 

/* class-specific code goes here */ 
return self; 

} 

This ensures that all inherited instance variables will also be unarchived. 

All implementations of the read: method should return self. 

After an object has been read, it’s sent an awake message so that it can reinitialize 
itself, and may also be sent a finishUnarchiving message. 

See also: - awake, - finishUnarchiving, - write: 
respondsTo: 

- (BOOL)respondsTo:(SEL)aSe/ecfc>r 

Returns YES if the receiver implements or inherits a method that can respond to 
aSelector messages, and NO if it doesn’t. The application is responsible for 
determining whether a NO response should be considered an error. 

Note that if the receiver is able to forward the aSelector message to another object, it 
will be able to respond to the message (albeit indirectly), even though this method 
returns NO. 

See also: - forward::, + instancesRespondTo: 

self 

- self 

Returns the receiver. 

See also: + class 
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startArchiving: 

- startArchiving: (NXTypedStream *)stream 

Implemented by subclasses to prepare an object for being archived—that is, for being 
written to the typed stream stream. A startArchiving: message is sent to an object just 
before it’s archived—but only if it implements a method that can respond. The message 
gives the object an opportunity to do anything necessary to get itself, or the stream, 
ready before a write: message begins the archiving process. 

There’s no default implementation of the startArchiving: method. The Object class 
declares the method, but doesn’t define it. 

See also: - awake, - finishUnarchiving, - write: 

subclassResponsibility: 

- subclassResponsibility :(SEL)aSelector 

Used in an abstract superclass to indicate that its subclasses are expected to implement 
aSelector methods. If a subclass fails to implement the method, the method is inherited 
from the superclass and an error is generated. 

For example, if subclasses are expected to implement doSomething methods, the 
superclass would define this version of the method: 

- doSomething 
{ 

[self subclassResponsibility:_cmd] ; 

} 

When this method is invoked, subclassResponsibility: will, working through Object’s 
error: method, abort the process and generate an appropriate error message. 

The _cmd variable identifies the current method selector, just as self identifies the 
current receiver. In the example above, it identifies the selector for the doSomething 
method. 

Subclass implementations of the aSelector method shouldn’t include messages to 
super to incorporate the superclass version. If they do, they’ll also generate an error. 

See also: - doesNotRecognize:, - notlmplemented:, - error: 

superclass 

- superclass 

Returns the class object for the receiver’s superclass. 

See also: + superclass 
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write: 


- write :(NXTypedStream *)stream 

Implemented by subclasses to write the receiver’s instance variables to the typed stream 
stream. You need to implement a write: method for any class you create if you want 
to be able to archive its instances (or instances of classes that inherit from it). 

The methods you implement should archive only the instance variables defined in the 
class, but should begin with a message to super so that all inherited instance variables 
will also be archived: 

- write:(NXTypedStream *)stream 
{ 

[super write:stream]; 

/* class-specific archiving code goes here */ 
return self; 

} 

All implementations of the write: method should return self. 

During the archiving process, write: methods may be performed twice, so they 
shouldn’t do anything other than write instance variables to a typed stream. 

See also: - read:, - start Archiving: 

zone 

- (NXZone *)zone 

Returns a pointer to the zone from which the receiver was allocated. Objects created 
without specifying a zone are allocated from the default zone, which is returned by 
NXDefauItMallocZoneO. 

See also: + allocFromZone:, + alloc, + copyFromZone: 
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Storage 


INHERITS FROM Object 

DECLARED IN objc/Storage.h 


CLASS DESCRIPTION 

The Storage class implements a general storage allocator. Each Storage object 
manages an array containing data elements of an arbitrary type. When an element is 
added to the object, it’s copied into the array. 

As is the case with List objects, Storage arrays grow dynamically when necessary. 
Their capacity doesn’t need to be explicitly adjusted. 

Because a Storage object holds elements of an arbitrary type, you don’t have to define 
a special class for each type of data you want to store. When setting up a new instance 
of the class, you specify the size of the elements and a description of their type. The 
type description is needed for archiving the object and must agree with the specified 
element size. It’s encoded in a string using the descriptor codes listed below: 


Type 

Code 

Type 

Code 

char 

c 

Class 

# 

char * 

* 

id 

@ 

NXAtom 

% 

SEL 


int 

i 

int (ignored) 

! 

short 

s 

structure 

{ <types>} 

float 

f 

array 

[ <countxtypes >] 

double 

example, 

d 

“[15d]” means an array of fifteen doubles, and 

“{csi*@}” means a 


structure containing a char, a short, an int, a character pointer, and an object. The 
descriptor specifies a unique string pointer. When it’s unarchived, the 
NXUniqueStringO function is used to make sure that it’s also unique within the new 
context. The “!” descriptor requires that the data be the same size as an int; the data 
won’t be archived. 


INSTANCE VARIABLES 
Inherited from Object 
Declared in Storage 


Class isa; 


void 

const char 
unsigned int 
unsigned int 
unsigned int 


*dataPtr; 

^description; 

numElements; 

maxElements; 

elementSize; 
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dataPtr 

description 

numElements 

maxElements 

elementSize 


A pointer to the data stored by the object. 

A string encoding the type of data stored. 

The number of elements actually in the Storage 
array. 

The total number of elements that can lit within 
currently allocated memory. 

The size of each element in the array. 


METHOD TYPES 

Initializing a new Storage instance - init 

- initCount:elementSize:description: 

Copying and freeing Storage objects 

- copy 

- copyFromZone: 

- free 

Getting, adding, and removing elements 

- addElement: 

- insertrat: 

- removeAt: 

- removeLastElement 

- replaceiat: 

- empty 

- elementAt: 

Comparing Storage objects - isEqual: 

Managing the storage capacity and type 

- count 

- description 

- setAvailableCapacity: 

- setNumSlots: 

Archiving - read: 

- write: 
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INSTANCE METHODS 


addElement: 

- addElement: (void *)anElement 

Adds anElement at the end of the Storage array and returns self. The size of the array 
is increased if necessary. 

See also: - insertiat: 

copy 

-copy 

Returns a new Storage object containing the same data as the receiver. The data as well 
as the object is copied, but the two objects share the same description string. Memory 
for the copy is taken from the same zone as the receiver. 

See also: - copyFromZone: 

copyFromZone: 

- copyFromZone :(NXZone *)zone 

Returns a new Storage object containing the same data as the receiver. The data as well 
as the object is copied, and memory for both is taken from zone. The two objects share 
the same description string. 

See also: - copy 

count 

- (unsigned)count 

Returns the number of elements currently in the Storage array. 

See also: - setNumSlots: 

description 

- (const char *)description 

Returns the string encoding the data type of elements in the Storage array. 

See also: - initCount:elementSize:description: 
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elementAt: 


- (void *)elementAt:(unsigned)zWejc 

Returns a pointer to the element at index in the Storage array. If no element is stored at 
index (index is beyond the end of the array), a NULL pointer is returned. 

Before using the pointer that’s returned, you must convert it into the appropriate type 
by a cast. The pointer can be used either to read the element at index or to alter it. 

See also: - replace:at:, - insert:at: 


empty 
- empty 

Empties the Storage array of all its elements and returns self. The current capacity of 
the array remains unchanged. 

See also: - free 


free 
- free 


Frees the Storage object and all the elements it contains. Pointers stored in the object 
will be freed, but the data they point to won’t be (unless the data is also stored in the 
object). You might want to free the data before freeing the Storage object. The 
description string isn’t freed. 

See also: - empty 

init 

- init 


Initializes the Storage object so that it’s ready to store object ids. The initial capacity 
of the array isn’t set. In general, it’s better to store object ids in a List object. Returns 
self. 

See also: - initCount:elementSize:description:, - initCount: (List) 
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initCount:elementSize:description: 

- initCount:(unsigned)a?w«£ 

elementSize : (\insigned)sizeInBy tes 
description: (const char *)string 

Initializes the Storage object so that it will have room for at least count elements. Each 
element is of size sizelnBytes and of the type described by string. If string is NULL, 
the object won’t be archivable. Once set, the description string should never be 
modified. Returns self. 

This method is the designated initializer for the class. It’s used to initialize Storage 
objects immediately after they have been allocated; it should never be used to 
reinitialize a Storage object that’s already been used. 

insertiat: 

- insert: (void *)anElement at:(unsigned )index 

Puts anElement in the Storage array at index. All elements between index and the last 
element are shifted to make room. The size of the array is increased if necessary. 
Returns self. 

See also: - addElement:, - setNumSlots: 
isEqual: 

- (BOOL)isEqual zanObject 

Compares the receiver with anObject , and returns YES if they’re the same and NO if 
they’re not. Two Storage objects are considered to be the same if they have the same 
number of elements and the elements at each position in the array match. 

read: 

- read:(NXTypedStream *)stream 

Reads the Storage object and the data it stores from the typed stream stream. 

See also: - write: 

removeAt: 

- removeAt: (unsigned)mdejt 

Removes the element located at index from the Storage array and returns self. All 
elements between index and the last element are shifted to close the gap. 

See also: - removeLastElement 
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removeLastElement 

- removeLastElement 

Removes the last element from the Storage array and returns self. 

See also: - remove At: 

replace:at: 

- replace:(void *)anElement at:(unsigned)zWex 

Replaces the data at index with the data pointed to by anElement. However, if no 
element is stored at index (index is beyond the end of the array), nothing is replaced. 
Returns self. 

See also: - elementAt:, - insertrat: 

set A vailableCapacity: 

- setAvailableCapacity:(unsigned)«wtf2S70fa 

Sets the storage capacity of the array to at least numSlots elements and returns self. If 
the array already contains more than numSlots elements, its capacity is left unchanged 
and nil is returned. 

See also: - setNumSlots:, - count 
setNumSlots: 

- setNumSlots :(unsigned)numSlots 

Sets the number of elements in the Storage array to numSlots and returns self. If 
numSlots is greater than the current number of elements in the array (the value returned 
by count), the new slots will be filled with zeros. If numSlots is less than the current 
number of elements in the array, access to all elements with indices equal to or greater 
than numSlots will be lost. 

If necessary, this method increases the capacity of the storage array so there’s room for 
at least numSlots elements. 

See also: - setAvailableCapacity:, - count 


write: 

- write :(NXTypedStream *)stream 

Writes the Storage object and its data to the typed stream stream. 
See also: - read: 
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StreamTable 


INHERITS FROM HashTable : Object 

DECLARED IN objc/StreamTable.h 

CLASS DESCRIPTION 

This class reads and writes a set of independent data structures on streams. Its goal is 
to provide incremental saving of files, as a cheap way to implement very primitive data 
bases. Both read and write operations are lazy, e.g., reading a StreamTable file only 
implies reading of the directory. 

Although StreamTable inherits from HashTable, very few methods can be directly 
inherited because internal representations of values differ. Nevertheless, the HashTable 
abstraction is retained, and StreamTable is described as an object class in order to 
simplify usage and implementation. The only inherited methods are count and isKey:. 
In order to read and write a StreamTable, the usual read: and write: methods can be 
performed. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from HashTable 

unsigned 

count; 


const char 

*keyDesc; 


const char 

*valueDesc; 

Declared in StreamTable 

(none) 



METHOD TYPES 

Creating and freeing a StreamTable 


Manipulating table elements 

Iterating over all elements 
Archiving 


- free 

- freeObjects 
+ new 

+ newKeyDesc: 

- insertStreamKey:value: 

- removeStreamKey: 

- valueForStreamKey: 

- initStreamState 

- nextStreamState:key:value: 

- read: 

- write: 
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CLASS METHODS 


new 
+ new 

Returns a new StreamTable with objects as keys. 

newKeyDesc: 

+ newKeyDesc: (const char *)aKeyDesc 

Returns a new StreamTable. Keys must be 32-bit quantities described by aKeyDesc. 


INSTANCE METHODS 

free 

- free 

Deallocates the table, but not the objects that are in the table. 

freeObjects 

- freeObjects 

Deallocates every object in the StreamTable, but not the StreamTable itself. Strings are 
not recovered. 

initStreamState 

- (NXHashState)initStreamState 

Iterating over all elements of a StreamTable involves setting up an iteration state, 
conceptually private to StreamTable, and then progressing until all entries have been 
visited. An example of counting elements in a table follows: 


unsigned count =0; 
const void *key; 
void *value; 

NXHashState state = [table initStreamState]; 

while ([table nextStreamState:Sstate key:&key value: Svalue]) 
count++; 


initState begins the process of iteration through the StreamTable. 
See also: nextStreamState:key:value: 
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insertStreamKeyivalue: 

- (id)insertStreamKey:(const void *)aKey value :(id)aValue 
Adds or updates akey/avalue pair. 

nextStr eamState: key: value: 

- (BOOL)nextStreamState:(NXHashState *)aState 

key:(const void **)aKey 
value:(id *)aValue 

Moves to the next entry in the StreamTable. No insertStreamKey: or 
removeStreamKey: should be done while iterating through the table. 

See also: initStreamState 

read: 

- read:(NXTypedStream *)stream 

Reads the StreamTable from the typed stream stream. 

removeStreamKey: 

- (id)removeStreamKey: (const void *)aKey 
Removes akey/avalue pair. Always returns nil. 

valueFor Str eamKey: 

- (id)valueForStreamKey:(const void *)aKey 

Returns the value mapped to aKey. Returns nil if aKey is not in the table. 

write: 

- write: (NXTypedStream *)stream 

Writes the StreamTable to the typed stream stream. 


Common Classes: StreamTable 2-61 




2-62 



Application Kit Classes 


The class specifications for the Application Kit describe over 50 classes. The inheritance 
hierarchy for these classes is shown in Figure 2-2. 
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ActionCell 


INHERITS FROM Cell: Object 

DECLARED IN appkit/ActionCell.h 

CLASS DESCRIPTION 

An ActionCell defines the active area inside a control (an instance of Control or one of 
its subclasses). You can set an ActionCell’s control only by sending the 
drawSelf:inView: message to the ActionCell, passing the control as the second 
argument. 

A single control may have more than one ActionCell. An integer tag, provided as the 
instance variable tag, is used to identify an ActionCell object; this is of particular 
importance to controls that contain more than one ActionCell. Note, however, that no 
checking is done by the ActionCell object itself to ensure that the tag is unique. See 
the Matrix class for an example of a subclass of Control that contains multiple 
ActionCells. 

ActionCell defines the target and action instance variables and methods for setting 
them. These define the ActionCell’s target object and action method. As the user 
manipulates a control, ActionCell’s trackMouse:inRect: ofView: method (inherited 
from Cell) sends the action message to the target object with the id of the Control object 
as the only argument. 

Many of the methods that define the contents and look of an ActionCell, such as 
setFont: and setBordered:, are reimplementations of methods inherited from Cell. 
They’re subclassed to ensure that the ActionCell is redisplayed if it’s currently in a 
control. 


INSTANCE VARIABLES 
Inherited from Object 
Inherited from Cell 


Declared in ActionCell 


tag 


Class 


isa; 


char 

id 

struct _cFlagsl 
struct _cFlags2 


^contents; 

support; 

cFlagsl; 

cFlags2; 


int 

id 

SEL 


tag; 

target; 

action; 


Reference number for the object. 


target 


The object’s notification target. 


action 


The message to send to the target. 
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METHOD TYPES 


Configuring the ActionCell 


Manipulating ActionCell values 


Displaying 
Target and action 


Assigning a tag 
Archiving 


- setAlignment: 

- setBezeled: 

- setBordered: 

- setEnabled: 

- setFloatingPointFormat:left:right: 

- setFont: 

- setlcon: 

- double Value 

- float Value 

- int Value 

- setStringValue: 

- setString ValueNoCopy: shouldFree: 

- string Value 

- controlView 

- drawSelfiinView: 

- action 

- setAction: 

- setTarget: 

- target 

- setTag: 

-tag 

- read: 

- write: 


INSTANCE METHODS 


action 

- (SEL)action 

Returns the selector for the receiver’s action method. Keep in mind that the argument 
to an ActionCell’s action method is the object’s Control (the object returned by 
controlView). 

See also: - setAction: 
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controlView 

- controlView 

Returns the Control object in which the receiver was most recently drawn. In general, 
you should use the object returned by this method only to (indirectly) redisplay the 
receiver. For example, the subclasses of ActionCell defined by the Application Kit 
invoke this method in order to send the returned object a message such as 

updateCelllnside:. 

The Control in which an ActionCell is drawn is set through the drawSelf :in View: 
method (only). 

See also: - drawSelf:inView: 

double Value 

- (double)double Value 

Returns the receiver’s contents as a double. 

See also: - setDoubleValue:(Cell), - double Value (Cell) 

dr awSelf: in V iew: 

- drawSelf: (const NXRect *)cellFrame inVievr.controlView 
Displays the ActionCell by sending 

[super drawSelf:cellFrarae inView:controlView]; 

Sets the receiver’s Control (the controlView instance variable) to controlView if and 
only if controlView is a Control object (in other words, an instance of Control or a 
subclass thereof). 

See also: - drawSelf:inView: (Cell) 

float Value 

- (float)floatValue 

Returns the receiver’s contents as a float. 

See also: - setFloatValue:(Cell), - floatValue (Cell) 
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intValue 

- (int)int Value 

Returns the receiver’s contents as an int. 

See also: - setIntVaIue:(Cell), - intValue (Cell) 

read: 

- read:(NXTypedStream *)stream 

Reads and returns an object of class ActionCell from stream. 

set Action: 

- setAction:(SEL)<zSWe<:tor 

Sets the receiver’s action method to aSelector. Keep in mind that the argument to an 
ActionCell’s action method is the object’s Control (the object returned by 
control View). Returns self. 

See also: - setTarget:, - send Action: to: (Control) 

set Alignment: 

- set Alignment :(int)ra<9(ie 

If the receiver is a text Cell (type NX_TEXTCELL), this sets its text alignment to mode, 
which should be NXLEFTALIGNED, NX_CENTERED, or NXJUGHTALIGNED. 
If it’s currently in a Control view, the receiver is redisplayed. Returns self. 

setBezeled: 

- setBezeled : (B OOLj/fag 

Adds or removes the receiver’s bezel, as flag is YES or NO. Adding a bezel will remove 
the receiver’s (flat) border, if any. If it’s currently in a Control view, the receiver is 
redisplayed. Returns self. 

See also: - setBordered: 

setBordered: 

- setBordered i(BOOL)flag 

Adds or removes the receiver’s border, as flag is YES or NO. The border is black and 
has a width of 1.0. Adding a border will remove the receiver’s bezel, if any. If it’s 
currently in a Control view, the receiver is redisplayed. Returns self. 

See also: - setBezeled: 
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setEnabled: 

- setEnabled:(BOOL)/7<2g 

Enables or disables the receiver’s ability to receive mouse events as flag is YES or NO. 
If it’s currently in a Control view, the receiver is redisplayed. Returns self. 

setFloatingPointFormat: left: right: 

- setFloatingPointFormat:(BOOL)awrc>/tarcge 

left: (unsigned int )leftDigits 
right: (unsigned int )rightDigits 

Sets the receiver’s floating point format. If it’s currently in a Control view, the receiver 
is redisplayed. Returns self. 

See also: - setFloatingPointFormat:left:right: (Cell) 

setFont: 

- setFont ifontObj 

If the receiver is a text Cell (type NX_TEXTCELL), this sets its font to fontObj. In 
addition, if it’s currently in a Control view, the receiver is redisplayed. Returns self. 

setlcon: 

- setlcon .‘(const char *)iconName 

Sets the receiver’s icon to iconName and sets its Cell type to NX_ICONCELL. If it’s 
currently in a Control view, the receiver is redisplayed. Returns self. 

See also: - setlcon: (Cell) 
setString Value: 

- setString Value: (const char *)aString 

Sets the receiver’s contents to a copy of aString. If it’s currently in a Control view, the 
receiver is redisplayed. Returns self. 

See also: - setString Value: (Cell) 
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setStringValueNoCopy.shouldFree: 

- setStringValueNoCopy:(char *)aString shouldFree:(BOOL)/Z<zg 

Sets the receiver’s contents to a aString. If flag is YES, aString will be freed when the 
receiver is freed. If it’s currently in a Control view, the receiver is redisplayed. Returns 
seif. 

See also: - setStringVaIueNoCopy:shouIdFree: (Cell) 


setTag: 

- setTag: (mt)anlnt 

Sets the receiver’s tag to anlnt. Returns self. 

setTarget: 

- setTargetianObject 

Sets the receiver’s target to anObject. Returns self. 

See also: - set Action: 

stringValue 

- (const char *)string Value 

Returns the receiver’s contents as a string. Returns self. 
See also: - setStringValue:, - stringValue (Cell) 


tag 

- (int)tag 

Returns the receiver’s tag. 

target 

- target 

Returns the receiver’s target. 

write: 

- write :(NXTypedStream *)stream 
Writes the receiver to stream. Returns self. 
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Application 


INHERITS FROM 
DECLARED IN 


Responder: Object 
appkit/Application.h 


CLASS DESCRIPTION 


The Application class provides the framework for program execution; every program 
must have exactly one Application object. Creating the object connects the program to 
the Window Server and initializes its PostScript environment. The Application object 
maintains a list of all the Windows in the application, thereby allowing it to retrieve 
every View in the application. To make it readily accessible to other objects, the 
Application object for your program is assigned to the global variable NXApp. 

The main task of the Application object is to receive events from the Window Server 
and distribute them to the proper Responders. System events are handled by the 
Application object itself. Window events are translated into event messages for the 
affected Window object. Key-down events that occur when the Command key is 
pressed are translated into commandKey: messages that every Window has an 
opportunity to respond to. Other keyboard and mouse events are sent to the Window 
associated with the event; the Window then distributes them to the objects in its view 
hierarchy. 

Subclassing the Application class is discouraged. Instead of placing the functionality 
of your program in an Application object, you should place that functionality in one or 
more modules which are subclasses of the Object class. Your program will then tend 
to be more reusable, and can be invoked from a small dispatcher object rather than 
being closely tied to the Application code. 

The Application object can be assigned a delegate that responds to notification 
messages on the Application object’s behalf. The easiest way to make your own object 
the Application object’s delegate is to Control-drag a connection from the File’s Owner 
icon to your object in Interface Builder, and connect it as the delegate. Many of the 
notification methods are sent back to the Application object if the delegate doesn’t 
respond, but the preferred technique is to have the delegate respond to these messages. 
The notification messages are listed below, divided into two categories: 


Delegate Only 

appDidHide: 

appDidUnhide: 

appWillUpdate: 

appDidUpdate: 

appDidB ecome Active: 

appDidResign Active: 

powerOff: 


Delegate or Application subclass 

appAcceptsAnotherFile: 
app:openFile:type: 
app: openTempFile :type: 
appDidlnit: 

app: powerOffln: andS ave: 
app: unmounting: 
applicationDefined: 
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Note that of the methods in the second category the Application class implements only 
the appIicationDefined: method, and that it implements that method only to forward 
the message to the delegate. 

Since an application must have one and only one Application object, you must use new 
to create it. You can’t use alloc, allocFromZone:, or init to create or initialize an 
Application object. 


INSTANCE VARIABLES 

Inherited from Object 
Inherited from Responder 
Declared in Application 


appName 


currentEvent 


windowList 


keyWindow 


Class 

isa; 

id 

nextResponder; 

char 

*appName; 

NXEvent 

currentEvent; 

id 

windowList; 

id 

keyWindow; 

id 

main Window; 

id 

delegate; 

int 

*hiddenList; 

int 

hiddenCount; 

const char 

*hostName; 

DPSContext 

context; 

int 

contextNum; 

id 

appListener; 

id 

appSpeaker; 

port_t 

replyPort; 

NXSize 

screenSize; 

short 

running; 

struct_appFlags { 


unsigned int 

hidden: 1; 

unsigned int 

autoupdate: 1; 

unsigned int 

active: 1; 

} 

appFlags; 


The name of your application; used by the 
defaults system and the application’s Listener 
object. 

The event most recently retrieved from the event 
queue. 

A List of all the windows belonging to the 
application. 

The Window that receives keyboard events. 
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mainWindow 


The Window that receives menu commands and 
action messages from a Panel. 


delegate 

The object that responds to delegated messages. 

hiddenList 

The Window Server’s List for Windows in the 
application at the time the application is hidden. 

hiddenCount 

The number of windows referred to by 

hiddenList. 

hostName 

The name of the machine running the Window 
Server. 

context 

The Display PostScript context connected to the 
Window Server. 

contextNum 

A number identifying the application’s Display 
PostScript context. 

appListener 

The Application object’s Listener. 

appSpeaker 

The Application object’s Speaker. 

replyPort 

A general purpose reply port for the Application 
object’s Speakers. 

screenSize 

The size of the screen that this application is 
running on. 

running 

The nested level of run and runModalFor:. 

appFlags.hidden 

YES if the application’s windows are currently 
hidden. 

appFlags.autoupdate 

YES if the Application object is to send an 
update message to each Window after an event 
has been processed. 

appFlags.active 

YES if the application is the active application. 
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METHOD TYPES 
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+ initialize 

+ new 

- free 

- loadNibFileiowner: 

- loadNibFile:owner:withNames: 

- loadNibFile: owner: withN ames: fromZone: 

- loadNibSection:owner: 

- loadN ibS ection: owner: withN ames: 

- loadNibSection: owner: withNames: 
fromHeader: 

- loadNibSection:owner:withNames: 
fromZone: 

- loadNibSection:owner:withNames: 
fromHeader:fromZone: 

- appName 

- setMainMenu: 

- mainMenu 

- activate: 

- activateSelf: 

- activeApp 

- becomeActiveApp 

- deactivates elf 

- isActive 

- resignActiveApp 

Running the event loop - run 

- stop: 

- runModalFor: 

- stopModal 

- stopModal: 

- abortModal 

- beginModalSession:for: 

- runModalSession: 

- endModalSession: 

- delayedFree: 

- isRunning 

- sendEvent: 

Getting and peeking at events - currentEvent 

- getNextEvent: 

- getNextEvent:waitFor:threshold: 

- peekAndGetNextEvent: 

- peekNextEvent:into: 

- peekNextEvent:into:waitFor:threshold: 


Initializing the class 
Creating and freeing instances 

Setting up the application 


Changing the active application 
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Journaling 


- isJoumalable 

- setJoumalable: 

- masterJoumaler 

- slaveJoumaler 

Handling user actions and events - applicationDefined: 

- hide: 

- isHidden 

- unhide 

- unhide: 

- unhideWithoutActivation: 

- powerOff: 

- powerOffhr.andSave: 

- rightMouseDown: 

- unmounting:ok: 

Sending action messages - sendAction:to:from: 

- tryToPerform:with: 

- calcTargetForAction: 

Remote messaging - setAppListener: 

- appListener 

- setAppSpeaker: 

- appSpeaker 

- appListenerPortName 

- reply Port 

Managing Windows - applcon 

- find Window: 

- getWindowNumbersxount: 

- key Window 

- mainWindow 

- makeWindowsPerform:inOrder: 

- set Autoupdate: 

- updateWindows 

- windowList 

Managing the Windows menu - setWindowsMenu: 

- windowsMenu 

- arrangelnFront: 

- addWindowsItem:title:filename: 

- removeWindowsItem: 

- changeWindowsItem:title:filename: 

- updateWindowsltem: 

Managing the Services menu - setServicesMenu: 

- servicesMenu 

- registerServicesMenuSendTypes: 

andRetumTypes: 

- validRequestorForSendType: andRetumTy pe : 
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Managing screens 

Querying the application 

Language 
Opening files 

Printing 

Color 

Terminating the application 
Assigning a delegate 


- mainScreen 

- colorScreen 

- getS creens: count: 

- getScreenSize: 

- context 

- focus View 

- hostName 

- systemLanguages 

- openFile:ok: 

- openTempFileiok: 

- setPrintlnfo: 

- printlnfo 

- runPageLayout: 

- orderFrontColorPanel: 

- terminate: 

- setDelegate: 

- delegate 


CLASS METHODS 

alloc 

Generates an error message. This method cannot be used to create an Application 
object. Use new instead. 

See also: + new 

allocFromZone: 

Generates an error message. This method cannot be used to create an Application 
object. Use new instead. 

See also: + new 

initialize 
+ initialize 

Registers defaults used by the Application class. You never send this message directly; 
it’s sent for you when your application starts. Returns self. 


2-76 Chapter 2: Class Specifications 



new 


+ new 

Creates a new Application object and assigns it to the global variable NXApp. A 
program can have only one Application object, so this method just returns NXApp if 
the Application object already exists. This method also makes a connection to the 
Window Server, loads the PostScript procedures the application needs, and completes 
other initialization. Your program should generally invoke this method as one of the 
first statements in main(); this is done for you if you create your application with 
Interface Builder. The Application object is returned. 

See also: - run 


INSTANCE METHODS 

abortModal 

- (void)abortModal 

Aborts the modal event loop by raising the NX_abortModal exception, which is caught 
by runModalFor:, the method that started the modal loop. Since this method raises an 
exception, it never returns; runModalFor:, when stopped with this method, returns 
NX_RUNABORTED. This method is typically invoked from procedures registered 
with DPSAddTimedEntryO, DPSAddPort(), or DPSAddFD(). Note that you can’t 
use this method to abort modal sessions, where you control the modal loop and 
periodically invoke runModalSession:. 

See also: - runModalFor:, - stopModal, - stopModal: 
activate: 

- (int)activate: (int )contextNumber 

Makes the application identified by contextNumber the active application. 
contextNumber is the PostScript context number of the application to be activated. 
Normally, you shouldn’t invoke this method; the Application Kit is responsible for 
proper activation. The previously active application’s PostScript context number is 
returned. 

See also: - isActive, - activateSelf:, - deactivateSelf 
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activateSelf: 

- (int)activateSelf:(BOOL)/fag 

Makes the receiving application the active application. If flag is NO, the application is 
activated only if no other application is currently active. Normally, this method is 
invoked with flag set to NO. When the Workspace Manager launches an application, 
it deactivates itself, so activateSelf:NO allows the application to become active if the 
user waits for it to launch, but the application remains unobtrusive if the user activates 
another application. If flag is YES, the application will always activate. Regardless of 
the setting of flag, there may be a time lag before the application activates; you should 
not assume that the application will be active immediately after sending this message. 

Note that you can make one of your Windows the key window without changing the 
active application; when you send a makeKey Window message to a Window, you 
simply ensure that the Window will be the key window when the application is active. 

You should rarely have a need to invoke this method. Under most circumstances the 
Application Kit takes care of proper activation. However, you might find this method 
useful if you implement your own methods for inter-application communication. This 
method returns the PostScript context number of the previously active application. 

See also: - activeApp, - activate:, - deactivates elf, - makeKeyWindow (Window) 

activeApp 

- (int)activeApp 

Returns the active application’s PostScript context number. If no application is active, 
returns zero. 

See also: - isActive, - activate: 

addWindowsItem:titIe:filename: 

- addWindowsItem^Wmdow titIe:(const char *)aString 

hlename:(BOOL)isFilename 

Adds an item to the Windows menu corresponding to the Window aWindow. If 
isFilename is NO, aString appears literally in the menu. If isFilename is YES, aString 
is assumed to be a converted name with the filename preceding the path, as placed in a 
Window title by Window’s setTitleAsFilename: method. If an item for aWindow 
already exists in the Windows menu, this method has no effect. You rarely invoke this 
method because an item is placed in the Windows menu for you whenever a Window’s 
title is set. Returns self. 

See also: - changeWindowsItem:title:filename:, - setTitle: (Window), 

- setTitleAsFilename: (Window) 
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applcon 

- applcon 

Returns the Window that represents the application in the Workspace Manager. 

applicationDefined: 

- applicationDefined :(NXEvent *)theEvent 

Handles the application-defined (NX_APPDEFINED) event theEvent. The default 
implementation forwards the message to the receiver’s delegate (if the delegate 
responds to the message). You should either provide a delegate implementation or 
override this method in your subclass of Application if you want to handle such events. 
If the delegate responds to this message, the delegate’s return value is returned; 
otherwise returns self. 

appListener 

- appListener 

Returns the Application object’s Listener—the object that will receive messages sent 
to the port that’s registered for the application’s name. If you don’t send a 
setAppListener: message before your application starts running, an instance of 
Listener is created for you. 

See also: - setAppListener:, - appListenerPortName, - run 

appListenerPortName 

- (const char *)appListenerPortName 

Returns the name used to register the Application object’s Listener. The default is the 
same name that’s returned by the Application object’s appName method. If a different 
name is desired, this method should be overridden. Messages sent by name to 
appListenerPortName will be received by your Application object. 

See also: - checklnAs: (Listener), - appName, NXPortFromName() 
appName 

- (const char *)appName 

Returns the name under which the Application object has been registered for defaults. 
This name is also used for messaging unless the messaging name was changed with an 
override of appListenerPortName. 

See also: - appListenerPortName 
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appSpeaker 

- appSpeaker 

Returns the Application object’s Speaker. You can use this object to send messages to 
other applications. 

See also: - setSendPort: (Speaker) 

arrangelnFront: 

- arrangelnFront:sender 

Arranges all of the windows listed in the Windows menu in front of all other windows. 
Windows associated with the application but not listed in the Windows menu are not 
ordered to the front. Returns self. 

See also: - removeWindowsItem:, - makeKeyAndOrderFront: (Window) 

becomeActiveApp 

- becomeActiveApp 

Sends the appDidBecomeActive: message to the Application object’s delegate. This 
method is invoked when the application is activated. You never send a 
becomeActiveApp message directly, but you can override this method in a subclass. 
Returns self. 

See also: - activateSelf:, - appDidBecome Active: (delegate) 
beginModalSession :for: 

- (NXModalSession *)beginModalSession:(NXModalSession *)session 

foritheWindow 

Prepares the application for a modal session with theWindow. In other words, prepares 
the application so that mouse events get to it only if they occur in theWindow. If session 
is NULL, a NXModalSession is allocated; otherwise the given storage is used. (The 
sender could declare a local NXModalSession variable for this purpose.) theWindow 
is made the key window and ordered to the front. 

beginModalSession:for: should be balanced by endModalSession:. If an exception 
is raised, beginModaISession:for: arranges for proper cleanup. Do NOT use 
NX_DURING constructs to send an endModalSession: message in the event of an 
exception. Returns the NXModalSession pointer that’s used to refer to this session. 

See also: - runModalSession:, - endModalSession: 
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calcTar getFor Action: 

- calcTargetForAction:(SEL)f/iMch<9rc 

Returns the first object in the responder chain that responds to the message theAction. 
The message isn’t actually dispatched. Note that this method doesn’t test the value that 
the responding object would return should the message be sent; specifically, it doesn’t 
test to see if the responder would return nil. Returns nil if no responder is found. 

See also: - sendAction:to:from: 

changeWindowsItem:title:filename: 

- changeWindowsItemitfWmdow title:(const char *)aString 

filename: (BOOL)isFilename 

Changes the item for aWindow in the Windows menu to aString. If aWindow doesn’t 
have an item in the Windows menu, this method adds the item. If isFilename is NO, 
aString appears literally in the menu. If isFilename is YES, aString is assumed to be a 
converted name with the filename preceding the path, as placed in a Window title by 
Window’s setTitleAsFilename: method. Returns self. 

See also: - addWindowsItem:title:filename:, - setTitle: (Window), 

- setTitleAsFilename: (Window) 

colorScreen 

- (const NXScreen *)colorScreen 

Returns the screen that can best represent color. This method will always return a 
screen, even if no color screen is present. 

See also: NXBPSFromDepth() 
context 

- (DPSContext)context 

Returns the Application object’s Display PostScript context. 

currentEvent 

- (NXEvent *)currentEvent 

Returns a pointer to the last event the Application object retrieved from the event queue. 
A pointer to the current event is also passed with every event message. 

See also: - getNextEvent:waitFor:threshold:, 

- peekNextE vent: waitFor: threshold: 
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deactivateSelf 

- deactivateSelf 

Deactivates the application if it’s active. Normally, you shouldn’t invoke this method; 
the Application Kit is responsible for proper deactivation. Returns self. 

See also: - activeApp, - activate:, - activateSelf: 

delayedFree: 

- delayedFree '.theObject 

Frees theObject by sending it the free message after the application finishes responding 
to the current event and before it gets the next event. If this method is performed during 
a modal loop, theObject is freed after the modal loop ends. Returns self. 

delegate 

- delegate 

Returns the Application object’s delegate. 

See also: - setDelegate: 

endModalSession: 

- endModalSession :(NXModalSession *)session 

Cleans up after a modal session, session should be from a previous invocation of 
beginModalSession: for:. 

See also: - runModalSession:, - beginModalSession:for: 
findWindow: 

- findWindow :(int) windowNum 

Returns the Window object that corresponds to the window number windowNum. This 
method is of primary use in finding the Window object associated with a particular 
event. 

See also: - windowNum (Window) 

focusView 

- focusView 

Returns the View that is currently focused on, or nil if no View is focused on. 

See also: - lockFocus (View) 
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free 


- free 

Closes all the Application object’s windows, breaks the connection to the Window 
Server, and frees the Application object. 

getNextEvent: 

- (NXEvent *)getNextEvent:(int)mas& 

Gets the next event from the Window Server and returns a pointer to its event record. 
This method is similar to getNextEvent:waitFor:threshold: with an infinite timeout 
and a threshold of NX_MODALRESPTHRESHOLD. 

See also: - getNextEvent:waitFor:threshold, - run, - runModalFor:, 

- currentEvent 

getNextEvent:waitFor:threshold: 

- (NXEvent *)getNextEvent:(int)mas£ 

waitFor:(doubl €)timeout 
threshold : (int )level 

Gets the next event from the Window Server and returns a pointer to its event record. 
Only events that match mask are returned; getNextEvent:waitFor:threshold: goes 
through the event queue, starting from the head, until it finds an event matching mask. 
Events that are skipped are left in the queue. Note that 
getNextEvent:waitFor:threshold: doesn’t alter the window event masks that 
determine which events the Window Server will send to the application. 

If an event matching the mask doesn’t arrive within timeout seconds, this method 
returns a NULL pointer. 

You can use this method to short circuit normal event dispatching and get your own 
events. For example, you may want to do this in response to a mouse-down event in 
order to track the mouse while it’s down. In this case, you would set mask to accept 
mouse-dragged, mouse-entered, mouse-exited, or mouse-up events. 

level determines what other tasks should be performed when the event queue is 
examined. Tasks that may be performed include procedures to deal with timed-entries, 
procedures to handle messages received on ports, or procedures to read new data from 
files. Any such procedure that needs to be called will be called if its priority (specified 
when the procedure is registered) is equal to or higher than level. 

In general, modal responders should pass NX_MODALRESPTHRESHOLD for level. 
The main run loop uses a threshold of NX_BASETHRESHOLD, allowing all 
procedures (except those registered with priority 0) to be checked and invoked if 
needed. 

See also: - peekNextEvent:waitFor:threshold:, - run, - runModalFor: 
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getScreens:count: 

- getScreens: (const NXScreen **)list count:(int *)numScreens 

Gets screen information for every screen connected to the system. A pointer to an array 
of NXScreen structures is placed in the variable indicated by list, and the number of 
NXScreen structures in that array is placed in the variable indicated by numScreens. 
Returns self. 

getScreenSize: 

- getScreenSize:(NXSize *)theSize 

Gets the size of the main screen, in units of the screen coordinate system, and places it 
in the structure pointed to by theSize. Returns self. 

getWindowNumbersicount: 

- getWindowNumbers:(int **)list count:(int *)numWindows 

Gets the window numbers for all the Application object’s Windows. A pointer to a 
non-NULL-terminated int array is placed in the variable indicated by list. The number 
of entries in this array is placed in the integer indicated by numWindows. The order of 
window numbers in the array is the same as their order in the Window Server’s screen 
list, which is their front-to-back order on the screen. The application is responsible for 
freeing the list array when done. Returns self. 

See also: NXWindowListO 
hide: 

- hid eisender 

Collapses the application’s graphics—including all its windows, menus, and panels— 
into a single small window. The hide: message is usually sent using the Hide command 
in the application’s main menu. Returns self. 

See also: - unhide: 

hostName 

- (const char *)hostName 

Returns the name of the host machine on which the Window Server that serves the 
Application object is running. This method returns the name that was passed to the 
receiving Application object through the NXHost default; this name is set either from 
its value in the defaults database or by providing a value for NXHost through the 
command line. If a value for NXHost isn’t specified, NULL is returned. 
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isActive 


- (BOOL)isActive 

Returns YES if the application is currently active, and NO if it isn’t. 

See also: - activateSelf:, - activate: 

isHidden 

- (BOOL)isHidden 

Returns YES if the application is currently hidden, and NO if it isn’t. 

isjournalable 

- (BOOL)isJournalable 

Returns YES if the application can be journaled, and NO if it can’t. By default, 
applications can be journaled. 

See also: - setjournalable: 

isRunning 

- (BOOL)isRunning 

Returns YES if the application is running, and NO if the stop: method has ended the 
main event loop. 

See also: - run, - stop:, - terminate: 

key Window 

- key Window 

Returns the key window—the Window that receives keyboard events. If there is no key 
window, or if the key window belongs to another application, this method returns nil. 

See also: - main Window, - isKey Window (Window) 
loadNibFile: owner: 

- loadNibFile:(const char *)filename owner :anOwner 

Loads objects from the specified interface file. This method is a cover for 
loadNibFile:owner:withNames:fromZone:. The objects and their names are read 
from the specified interface file into storage allocated from the default zone. Returns 
non-nil if the file filename is successfully opened and read; otherwise it returns nil. 

See also: - loadNibFile:owner:withNames:fromZone:, NXDefaultMallocZoneQ 
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loadNibFile:owner:withNames: 

- loadNibFile: (const char *) filename 

own&r.anObject 
withNames: (QOOlflflag 

Loads objects from the specified interface file. This method is a cover for 
loadNibFi!e:owner:withNames:fromZone:. The objects are read from the specified 
interface file into storage allocated from the default zone. Returns non-nil if the file 
filename is successfully opened and read; otherwise it returns nil. 

See also: - loadNibFile:owner:withNames:fromZone:, NXDefaultMallocZoneO 

loadNibFile:owner:withNames:fromZone: 

- loadNibFile:(const char *)filename 

owner '.anObject 
withN ames: (B OOL)flag 
fromZone:(NXZone *)zone 

Loads objects from the specified interface file into memory allocated from zone. This 
method returns non-nil if the file filename is successfully opened and read; otherwise it 
returns nil. 

anObject is the object that corresponds to the “File’s Owner” object in Interface 
Builder’s File window. As the objects are loaded, the outlet initialization methods in 
anObject are invoked to bind the outlets. 

If flag is YES, the names of the objects are loaded. If you use only the outlet 
mechanism to get to objects in the interface file, you can save some memory by 
specifying NO as the value of flag. However, you won’t be able to use 
NXGetNamedObject() to get at the objects. 

See also: - loadNibSection:owner:withNames:fromZone: 
loadNibSectionrowner: 

- loadNibSection:(const char *)sectionName owner '.anObject 

Loads objects and their names from the specified section of the application’s executable 
file into memory allocated from the default zone. This method returns non-nil if the 
section is successfully loaded; otherwise it returns nil. 

See also: - loadNibSection:owner:withNames:fromZone:, 
NXDefaultMallocZoneO 
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loadN ibSection :owner: withNames: 

- loadNibSection:(const char *)name 

owner :anObject 
withNames: (BOOL)flag 

Loads objects from the interface data in the specified section in the_ NIB segment of 

the executable file into memory allocated from the default zone. This method returns 
non-nil if the section is successfully loaded; otherwise it returns nil (for example if 
section name doesn’t exist). 

See also: - loadNibSection:owner:withNames:fromZone:, 
NXDefaultMallocZone() 

loadNibSection: owner: withN ames: fr omHeader: 

- loadNibSection:(const char *)name 

ownerianObject 
withNames: (B OOL)fl ag 

fromHeader: (const struct mach_header *)header 

Loads objects from a dynamically loaded header into memory allocated from the 
default zone. A class can use this method in its + finishLoading method to load 
associated interface data. 

See also: - loadNibSection:owner:withNames:fromZone:, 
NXDefaultMallocZoneO 

loadNibSection: owner: withN ames :fr omHeader: fromZone: 

- loadNibSection: (const char *)name 

owner :anObject 
withN ames: (B OOL)flag 

fromHeader: (const struct mach_header *)header 
fromZone :(NXZone *)zone 

Loads objects from a dynamically loaded header into memory allocated from the 
specified zone. A class can use this method in its + load method to load associated 
interface data. 

See also: - loadNibSection:owner:withNames:fromZone: 
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loadNibSection:owner:withNames:fromZone: 

- loadNibSection:(const char *)name 

owner :anObject 
withNames: (B OOL)flag 
fromZone:(NXZone *)zone 

Loads objects from the interface data in the specified section in the_NIB segment of 

the executable file into memory allocated from the specified zone. This method returns 
non-nil if the section is successfully loaded; otherwise it returns nil (for example if 
section name doesn’t exist). 

anObject is the object that corresponds to the “File’s Owner” object in the Interface 
Builder’s File window. As the objects are loaded, the outlet initialization methods in 
anObject are performed to bind the outlets. 

If flag is YES, the names of the objects are loaded. If you use only the outlet 
mechanism to get to objects in the interface section, you can save some memory by 
specifying NO as the value of flag. In that case you won’t be able to use 
NXGetNamedObject() to get the id of objects. 

See also: - loadNibSection:owner:withNames:fromZone: 

mainMenu 

- mainMenu 

Returns the Application object’s main menu. 

mainScreen 

- (const NXScreen *)mainScreen 

Returns the main screen. If there is only one screen, that screen is returned. Otherwise, 
this method attempts to return the key window’s screen. If there is no key window, it 
attempts to return the main menu’s screen. If there is no main menu, this method 
returns the screen that contains the screen coordinate system origin. 

See also: - screen (Window) 

mainWindow 

- mainWindow 

Returns the main window. This method returns nil if there is no main window, if the 
main window belongs to another application, or if the application is hidden. 

See also: - key Window, - isMain Window (Window) 
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makeWindowsPerform:inOrder: 

- makeWindowsPerform:(SEL )aSelector inOrder :(BOOL)flag 

Sends the Application object’s Windows a message to perform the aSelector method. 
The message is sent to each Window in turn until one of them returns YES; this method 
then returns that Window. If no Window returns YES, this method returns nil. 

If flag is YES, the Application object’s Windows receive the aSelector message in the 
front-to-back order in which they appear in the Window Server’s window list. If flag is 
NO, Windows receive the message in the order they appear in the Application object’s 
window list. This order generally reflects the order in which the Windows were 
created. 

The aSelector method can’t take any arguments. 

master Journaler 

- master Journaler 

Returns the Application object’s master journaler. 

See also: - slaveJounaler 

openFile:ok: 

- (int)openFile: (const char *)fullPath ok:(int *)flag 

Responds to a remote message requesting the application to open a file. The 
openFile:ok: message is typically sent to the application from the Workspace 
Manager, although other applications can send it directly to a specific application. The 
Application object’s delegate is queried with the appAcceptsAnotherFile: message 
and if the result is YES, it’s sent the app:openFile:type: message. If the delegate 
doesn’t respond to either of these messages, they’re sent to the Application object (if it 
implements them). 

The variable pointed to by flag is set to YES if the file is successfully opened, NO if the 
file is not successfully opened, and (-1) if the application does not accept another file. 
Returns zero. 

See also: - app:openFile:type: (Application delegate), - openFile:ok: (Speaker) 
openTempFilerok: 

- (int)openTempFile: (const char *)fullPath ok:(int *)fLag 

Same as the openFile:ok: method, but app:openTempFile:type: is sent. Returns zero. 

See also: - app:openTempFile:type: (Application delegate), 

- openTempFile:ok: (Speaker) 
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orderFrontColorPanel: 

- orderFrontColorPanehsmier 

Displays the color panel. Returns self. 

peek AndGetNextE vent: 

- (NXEvent *)peekAndGetNextEvent:(int)m<zs& 

This method is similar to getNextEvent:waitFor:threshold: with a zero timeout and 
a threshold of NX_MODALRESPTHRESHOLD. 

See also: - getNextEvent:waitFor:threshold, - run, - runModalFor:, 

- currentEvent 

peekNextEvent:into: 

- (NXEvent *)peekNextEvent:(int)mtfs& into: (NXEvent *)eventPtr 

This method is similar to peekNextEvent:into:waitFor:thresho!d: with a zero 
timeout and a threshold of NX_MODALRESPTHRESHOLD. 

See also: - peekNextEvent:into:waitFor:threshold, - run, - runModalFor:, 

- currentEvent 

peekNextEvent:into:waitFor:threshold: 

- (NXEvent *)peekNextEvent:(int)mas& 

into:(NXEvent *)eventPtr 
waitFor:(float )timeout 
threshold: (int )level 

This method is similar to getNextEvent:waitFor:threshold: except the matching 
event isn’t removed from the event queue nor is it placed in currentEvent; instead, it’s 
copied into storage pointed to by eventPtr. 

If no matching event is found, NULL is returned; otherwise, eventPtr is returned. 

See also: - getNextEvent:waitFor:threshold:, - run, - runModalFor:, 

- currentEvent 


2-90 Chapter 2: Class Specifications 



powerOff: 

- powerOff: (NXEvent *)theEvent 

A powerOff: message is generated when a power-off event is sent from the Window 
Server. If the application was launched by the Workspace Manager, this method does 
nothing; instead, the Application object will wait for the powerOffln:andSave: 
message from the Workspace Manager. If the application wasn’t launched from the 
Workspace Manager, this method sends the delegate a powerOff: message, assuming 
there’s a delegate and it implements the method. Returns self. 

powerOffIn:andSave: 

- (int)powerOffln:(int)ms andSave:(int)tfF/tfg 

You never invoke this method directly; it’s sent from the Workspace Manager. The 
delegate or your subclass of Application will be given the chance to receive the 
app:powerOffln:andSave message. This method raises an exception, so it never 
returns. 

See also: - app:powerOffIn:andSave: (delegate) 

printlnfo 

- printlnfo 

Returns the Application object’s global Printlnfo object. If none exists, a default one 
is created. 

registerServicesMenuSendTypesrandReturnTypes: 

- registerServicesMenuSendTypes: (const char *const *)sendTypes 

andReturnTypes: (const char *const *)returnTypes 

Registers pasteboard types that the application can send and receive in response to 
service requests. If the application has a Services menu, a menu item is added for each 
service provider that can accept one of the specified send types or return one of the 
specified return types. This method should typically be invoked at application startup 
time or when an object that can use services is created. It can be invoked more than 
once; its purpose is to ensure that there is a menu item for every service that may be 
used by the application. The individual items will be dynamically enabled and disabled 
by the event handling mechanism to indicate which services are currently appropriate. 
An application (or object instance that can cut or paste) should register every possible 
type that it can send and receive. Returns self. 

See also: - validRequestorForSendType:andReturnType: (Responder), 

- readSelectionFromPasteboard: (Object method), 

- writeSelectionToPasteboard: (Object method) 
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removeWindowsItem: 

- removeWindowsItem :aWindow 

Removes the item for aWindow in the Windows menu. Returns self. 

See also: - changeWindowsItem:title:fiIename: 

replyPort 

- (port _t)rep!yPort 

Returns the Application object’s reply port. This port is allocated for you automatically 
by the run method, and is the default reply port which can be shared by all the 
Application object’s Speakers. 

See also: - setReplyPort: (Speaker) 

resignActiveApp 

- resignActiveApp 

This method is invoked immediately after the application is deactivated. You never 
send resignActiveApp messages directly, but you could override this method in your 
Application object to notice when your application is deactivated. Alternatively, your 
delegate could implement appDidResignActive:. Returns self. 

See also: - deactivateSelf:, - appDidResignActive: (delegate) 
rightMouseDown: 

- rightMouseDown :(NXEvent *)theEvent 
Pops up the main menu. Returns self. 

run 

- run 

Initiates the Application object’s main event loop. The loop continues until a stop: or 
terminate: message is received. Each iteration through the loop, the next available 
event from the Window Server is stored, and is then dispatched by sending the event to 
the Application object using sendEvent: 

A run message should be sent as the last statement from main(), after the application’s 
objects have been initialized. Returns self if terminated by stop:, but never returns if 
terminated by terminate:. 

See also: - runModalFor:, - sendEvent:, - stop:, - terminate:, 

- appDidlnit: (delegate) 
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runModalFor: 

- ( int)runModa\For:theWindow 

Establishes a modal event loop for theWindow. Until the loop is broken by a 
stopModal, stopModal:, or abortModal message, the application won’t respond to 
any mouse, keyboard, or window-close events unless they’re associated with 
theWindow. If stopModal: is used to stop the modal event loop, this method returns 
the argument passed to stopModal:. If stopModal is used, it returns the constant 
NX_RUNSTOPPED. If abortModal is used, it returns the constant 
NX_RUNABORTED. This method is functionally similar to the following: 

NXModalSession session; 

[NXApp beginModalSession:Ssession for:theWindow]; 
for (;;) { 

if ([NXApp runModalSession:^session] != NX_RUNCONTINUES) 
break; 

} 

[NXApp endModalSession:^session]; 

See also: - stopModal, - stopModal:, - abortModal, - runModalSession: 
runModalSession: 

- (int)runModalSession:(NXModalSession *)session 

Runs a modal session represented by session, as defined in a previous invocation of 
beginModalSession:for:. A loop using this method is similar to a modal event loop 
run with runModalFor:, except that with this method the application can continue 
processing between method invocations. When you invoke this method, events for the 
window of this session are dispatched as normal; this method returns when there are no 
more events. You must invoke this method frequently enough that the window remains 
responsive to events. 

If the modal session was not stopped, this method returns NX_RUNCONTINUES. If 
stopModal was invoked as the result of event procession, NX_RUNSTOPPED is 
returned. If stopModal: was invoked, this method returns the value passed to 
stopModal:. The NX_abortModal exception raised by abortModal isn’t caught. 

See also: - beginModalSession:, - endModalSession, - stopModal:, - stopModal, 

- runModalFor: 

runPageLayout: 

- runPageLayout: sender 

Brings up the Application object’s Page Layout panel, which allows the user to select 
the page size and orientation. Returns self. 
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sendAction:to:from: 


- (BOOL)sendAction:(SEL)<2Se/ecf£>r toiaTarget from '.sender 

Sends an action message to an object. If aTarget is nil, the message is sent down the 
responder chain. Returns YES if the action is applied; otherwise returns NO. 

sendEvent: 

- sendEvent :(NXEvent *)theEvent 

Sends an event to the Application object. You rarely send sendEvent: messages 
directly although you might want to override this method to perform some action on 
every event. sendEvent: messages are sent from the main event loop (the run method). 
sendEvent is the method that dispatches events to the appropriate responders; the 
Application object handles application events, the Window indicated in the event 
record handles window related events, and mouse and key events are forwarded to the 
appropriate Window for further dispatching. Returns self. 

See also: - set Autoupdate: 

servicesMenu 

- servicesMenu 

Returns the Application object’s Services menu. Returns nil if no Services menu has 
been created. 

See also: - setServicesMenu: 

setAppListener: 

- setAppListener :aListener 

Sets the Listener that will receive messages sent to the port that’s registered for the 
application. If you want to have a special Listener reply to these messages, you must 
either send a setAppListener: message before the run message is sent to the 
Application object, or send this message from the delegate method appWilllnit:, so 
that aListener is properly registered. This method doesn’t free the Application object’s 
previous Listener object. Returns self. 

See also: - appListenerPortName, - appWilllnit: (delegate) 
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setAppSpeaker: 

- setAppSpeaker laSpeaker 

Sets the Application object’s Speaker. If you don’t send a setAppSpeaker: message 
before the Application object initializes, a default Speaker is created for you. This 
method doesn’t free the Application object’s previous Speaker object. 

See also: - appWilllnit: (delegate) 

setAutoupdate: 

- setAutoupdate:(BOOL)/fag 

Turns on or off automatic updating of windows. If automatic updating is on, update is 
sent to each of the application’s Windows after each event has been processed. This 
can be used to keep the appearance of menus and panels synchronized with your 
application. Returns self. 

setDelegate: 

- setDeXegateianObject 

Sets the Application object’s delegate. The notification messages that a delegate can 
expect to receive are listed at the end of the Application class specifications. The 
delegate doesn’t need to implement all the methods. Returns self. 

See also: - delegate 

setjournalable: 

- setjournalable :(BOOL)flag 

Sets whether the application is joumalable. Returns self. 

setMainMenu: 

- setMmnMenuiaMenu 

Makes aMenu the Application object’s main menu. Returns self. 

See also: - mainMenu 

setPrintlnfo: 

- setPrintlnfo :m/o 

Sets the Application object’s global Printlnfo object. Returns the previous Printlnfo 
object, or nil if there was none. 
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setSer vicesMenu: 

- setServicesMenu:<2M<?/?« 

Makes aMenu the Application object’s Services menu. Returns self. 

set WindowsMenu: 

- setWindowsMenu 

Makes aMenu the Application object’s Windows menu. Returns self. 

slavejournaler 

- slavejournaler 

Returns the Application object’s slavejournaler. 

stop: 

- stop '.sender 

Stops the main event loop. This method will break the flow of control out of the run 
method, thereby returning to the main() function. A subsequent run message will 
restart the loop. 

If this method is applied during a modal event loop, it will break that loop but not the 
main event loop. Returns self. 

See also: - terminate:, - run, - runModalFor:, - runModalSession: 

stopModal 

- stopModal 

Stops a modal event loop. This method should always be paired with a previous 
runModalFor: or beginModalSession:for: message. When runModalFor: is 
stopped with this method, it returns NX_RUNSTOPPED. This method will stop the 
loop only if it’s executed by code responding to an event. If you need to stop a 
runModalFor: loop from a procedure registered with DPSAddTimedEntryO, 
DPSAddPortQ, or DPSAddFDQ, use the abortModal method. Returns self. 

See also: - runModalFor:, - runModalSession:, - abortModal 
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stopModal: 

- stopModah(int)returnCode 

Just like stopModal except argument retumCode allows you to specify the value that 
runModalFor: will return. Returns self. 

See also: - stopModal, - runModalFor:, - abortModal 
systemLanguages 

- (const char *const *)systemLanguages 

Returns a NULL-terminated list of NULL-terminated strings which specify the user’s 
preferred languages (human languages, not computer languages) in order of 
preference. If this method returns NULL, the user has no preference. This should be 
used to do any localization of your application. 

terminate: 

- termlnateisender 

Terminates the application. This method invokes appWillTerminate: to notify the 
delegate that the application will terminate. If appWillTerminate: returns nil, 
terminate: returns self; control is returned to the main event loop, and the application 
isn’t terminated. Otherwise, this method frees the Application object and terminates 
the application by using exit(). terminate: is the default action method for the 
application’s “Quit” menu item. Note that you should not put final cleanup code in your 
application’s main() function; it will never be executed. 

See also: - stop, - appWillTerminate: (delegate), exit() 

tryToPerformrwith: 

- (BOOL)tryToPerform:(SEL)&SWector with tanObject 

Aids in dispatching action messages. The Application object tries to perform the 
method selector aSelector using its inherited Responder method tryToPerfornr.with:. 
If the Application object doesn’t perform aSelector, the delegate is given the 
opportunity to perform it using its inherited Object method perform:with:. If either 
the Application object or the Application object’s delegate accept aSelector, this 
method returns YES; otherwise it returns NO. 

See also: - tryToPerfornr.with: (Responder), - respondsTo: (Object), 

- perform:with: (Object) 
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unhide 


- (int)unhide 

Responds to an unhide message sent from Workspace Manager. You shouldn’t invoke 
this method; invoke unhide: instead. Returns zero. 

See also: - unhide: 

unhide: 

- unhide '.sender 

Restores a hidden application to its former state (all of the windows, menus, and panels 
visible), and makes it the active application. This method is usually invoked as the 
result of double-clicking in the icon for the hidden application. Returns self. 

See also: - hide:, - unhide Without Activation:, - activateSelf: 
unhide Without Activation: 

- unhide Without Activation:.ve«c/<?/ 

Unhides the application but does not make it the active application. You might want to 
invoke activateSelf:NO after invoking this method to make the receiving application 
active if there is no active application. Returns self. 

See also: - hide:, - activateSelf: 
unmounting:ok: 

- (int)unmounting: (const char *)fullPath ok:(int *)flag 

Replies to an unmounting:ok: message sent from the Workspace Manager. You 
shouldn’t directly send unmounting:ok: messages. This method attempts to invoke 
the app:unmounting: method of the Application object’s delegate or of the 
Application object itself. If neither object implements app:unmounting:, and the 
current working directory is on the same volume as fullPath, this method changes the 
working directory to the user’s home directory. Returns zero. 

updateWindows 

- updateWindows 

Sends an update message to the Application object’s visible Windows. If automatic 
updating is enabled, this method is invoked automatically in the main event loop after 
each event. An application can also send updateWindows messages at other times to 
have Windows update themselves. 
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If the delegate implements appWillUpdate:, that message is sent to the delegate before 
the windows are updated. Similarly, if the delegate implements appWillUpdate:, that 
message is sent to the delegate after the windows are updated. Returns self. 

See also: - setAutoupdate:, - appWillUpdate: (delegate), 

- appDidUpdate: (delegate) 

updateWindowsItem: 

- updateWindowsItem :vvm 

Updates the item for aWindow in the Windows menu to reflect the edited status of 
aWindow. You rarely need to invoke this method because it is invoked automatically 
when the edited status of a Window is set. Returns self. 

See also: - changeWindowsItem:title:filename:, - setDocEdited: (Window) 

validRequestorForSendType:andReturnType: 

- validRequestorFor SendTy pe: (NX Atom )sendType 

andReturnTy pe : (NX Atom )returnType 

Passes this message on to the Application object’s delegate, if the delegate can respond 
(and isn’t a Responder with its own next responder). If the delegate can’t respond or 
returns nil, this method returns nil, indicating that no object was found that could 
supply typeSent data for a remote message from the Services menu and accept back 
typeReturned data. If such an object was found, it is returned. 

Messages to perform this method are initiated by the Services menu. This method 
might not be in the Application class header file at this time. 

See also: - validRequestorForSendType:andReturnType: (Responder), 

- registerServicesMenuSendTypes:andReturnTypes:, 

- writeSelectionToPasteboard.'types: (Object Method), 

- readSelectionFromPasteboard: (Object Method) 

windowList 

- windowList 

Returns the List object used to keep track of the Application object’s Windows. 

windowsMenu 

- windowsMenu 

Returns the Application object’s Windows menu. Returns nil if no Windows menu has 
been created. 
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METHODS IMPLEMENTED BY THE DELEGATE 


app:openFile:type: 

- (int)app lewder openFile: (const char *)filename type:(const char *)aType 

Invoked from within openFi!e:ok: after it has been determined that the application can 
open another file. The method should attempt to open the file filename with the 
extension aType, returning YES if the file is successfully opened, and NO otherwise. 

This method is also invoked from within openTempFile:ok: if neither the delegate nor 
the Application subclass responds to app:openTempFile:type: 

See also: - openFile:ok:, - openTempFile:ok: 
app: openTempFile: ty pe: 

- (int)app:,sc«dcr openTempFile:(const char *)filename type:(const char *)aType 

Invoked from within openTempFile:ok: after it has been determined that the 
application can open another file. The method should attempt to open the file filename 
with the extension aType , returning YES if the file is successfully opened, and NO 
otherwise. 

By design, a file opened through this method is assumed to be temporary; it’s the 
application’s responsibility to remove the file at the appropriate time. 

See also: - openTempFile:ok: 

app:powerOffTn:andSave: 

- app '.sender powerOffTn:(int)m andSave:(int)aF/ag 

Invoked when the Application object receives a power-off event through the 
powerOffIn:andSave: method. This method is invoked only if the application was 
launched from the Workspace Manager, ms is the number of milliseconds to wait 
before powering down or logging out. aFlag has no particular meaning at this time. 
You can ask for additional time by sending the extendPowerOffBy.actual: message 
to the Workspace Manager. The Workspace Manager will power the machine down (or 
log out the user) as soon as all applications terminate, even if there’s time remaining on 
the time extension. 

See also: - extendPowerOffBy:actuaI: (Speaker) 
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app:unmounting: 

- (int)app:sender unmounting: (const char *)fullPath 

Invoked when the device mounted alfullPath is about to be unmounted. This method 
is invoked from unmounting:ok: and is invoked only if the application was launched 
from the Workspace Manager. The Application object or its delegate should do 
whatever is necessary to allow the device to be unmounted. Specifically, all files on the 
device should be closed and the current working directory should be changed if it’s on 
the device. 

app Accepts AnotherFile: 

- (BOOL)app Accepts AnotherFile:s<?ttd<?r 

Invoked from within Application’s openFile:ok: and openTempFile:ok: methods, this 
method should return YES if it’s okay for the application to open another file, and NO 
if isn’t. If neither the delegate nor the Application object responds to the message, then 
the file shouldn’t be opened. 

See also: - openFile:ok:, - openTempFile:ok: 

appDidBecome Active: 

- appDidBecomeActive:sender 

Invoked immediately after the application is activated. 

appDidHide: 

- appDidHide:se«der 

Invoked immediately after the application is hidden. 

appDidlnit: 

- appDidlnit '.sender 

Invoked after the application has been launched and initialized, but before it has 
received its first event. The delegate or the Application subclass can implement this 
method to perform further initialization. 

See also: - appWilllnit: (delegate) 

appDidResign Active: 

- appDidResignActive:sewder 

Invoked immediately after the application is deactivated. 
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appDidUnhide: 

- appDidUnhide:.se/Mfer 

Invoked immediately after the application is unhidden. 

appDidUpdate: 

- appDidUpdate:^«d'er 

Invoked immediately after the Application object updates its Windows. 

applicationDedned: 

- applicationDefined:(NXEvent *)theEvent 

Invoked when the application receives an application-defined (NX_APPDEFINED) 
event. See the description of this method under INSTANCE METHODS, above. 

appWilllnit: 

- appWillInit:sera/er 

Invoked before the Application object is initialized. This method is invoked before the 
Application object has initialized its Listener and Speaker objects and before any 
app:openFile:type: messages are sent to your delegate. The Application object’s 
Listener and Speaker objects will be created for you immediately after invoking this 
method if they have not been previously created. 

See also: - appDidlnit: (delegate), - appListener, - appSpeaker 

appWillTerminate: 

- appWillTerminate: 56 «<ier 

Invoked from within the terminate: method immediately before the application 
terminates. If this method returns nil, the application is not terminated, and control is 
returned to the main event loop. If you want to allow the application to terminate, you 
should put your clean up code in this method and return non-nil. 

See also: - terminate: 

appWillUpdate: 

- appWillUpdate^eflder 

Invoked immediately before the Application object updates its Windows. 
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power Off: 

- power Off: (NXEvent *)theEvent 


Invoked when the Application object receives a power-off event through the power Off: 
method. Note that powerOff: (and so, too, this method) is invoked only if the 
application wasn’t launched from the Workspace Manager. 


CONSTANTS AND DEFINED TYPES 


/* KITDEFINED subtypes */ 
#define NX_WINEXPOSED 0 

#define NX_APPACT 1 

#define NX_APPDEACT 2 

#define NX_WINRESIZED 3 

#define NX_WINMOVED 4 

#define NX_SCREENCHANGED 8 

/* SYSDEFINED subtypes */ 
#define NX POWEROFF 1 


/* Additional flags */ 

#define NX_JOURNALFLAG 31 

#define NX_JOURNALFLAGMASK (1 « NX_JOURNALFLAG) 

/* Thresholds passed to DPSGetEvent () and DPSPeekEvent(). */ 
#define NX_BASETHRESHOLD 1 

#define NX_RUNMODALTHRESHOLD 5 
#define NX MODALRESPTHRESHOLD 10 


/* 

* Predefined return values for runModalFor: and 

* runModalSession: . All values below these (-1003, -1004, and 

* so on) are also reserved. 

*/ 

#define NX_RUNSTOPPED (-1000) 

#define NX_RUNABORTED (-1001) 

#define NX_RUNCONTINUES (-1002) 
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/* 

* The NXModalSession structure contains information used by the 

* system between beginModalSession:for : and endModalSession: 

* messages. This structure can either be allocated on the stack 

* frame of the caller, or by beginModalSession: for :. The 

* application should not access any of the elements of this 

* structure. 

*/ 

typedef struct _NXModalSession { 
id app; 
id window; 

struct __NXModalSession *prevSession; 
int oldRunningCount; 

BOOL oldDoesHide; 

BOOL freeMe; 
int winNum; 

NXHandler *errorData; 
int reservedl; 
int reserved2; 

} NXModalSession; 
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INHERITS FROM 


View : Responder : Object 


DECLARED IN appkit/Box.h 

CLASS DESCRIPTION 

A Box is a View that visually groups other Views. A Box has one subview, its content 
view , which is used to group the Box’s contents. A Box also typically displays a title 
and a border around its content view. The Box class includes methods to change the 
Box’s border style and title position, and to set the text and font of the title. In addition, 
you can add subviews to the Box’s content view and then resize the Box to fit around 
these subviews. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Declared in Box 

id 

cell; 


id 

contentView; 


NXSize 

offsets; 


NXRect 

borderRect; 


NXRect 
struct _bFlags { 

titleRect; 


unsigned int 

borderType:2; 


unsigned int 

titlePosition:3 


unsigned int 

transparent:!; 


} bFlags; 

cell The cell that draws the Box’s title. 

contentView The Box’s subview that contains the Views that 

are grouped within the Box. 

offsets Offset of the content view from the Box’s border. 

borderRect The Box’s border rectangle. 
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titleRect 

bFlag s. borderTy pe 
bFlags.titlePosition 
bFlags.transparent 


The location of the title cell. 
Indicates the Box’s border type. 
Indicates the Box’s title position. 
Reserved. Do not use. 


METHOD TYPES 


Initializing a new Box object 

- initFrame: 

Freeing a Box object 

- free 

Modifying graphic attributes 

- setBorderType: 

- borderType 

- setOffsets:: 

- getOffsets: 

Modifying the title 

- cell 

- setFont: 

- font 

- setTitle: 

- title 

- setTitlePosition: 

- titlePosition 

Putting Views in the Box 

- addSubview: 

- setContentView: 

- content View 

Resizing the Box 

- setFrameFromContentFrame: 

- sizeTo:: 

- sizeToFit 

Drawing the Box 

- drawSelf:: 

Archiving 

- awake 

- read: 

- write: 
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INSTANCE METHODS 


addSubview: 

- addSubviewr^Vfew 

Adds aView as a subview of the Box’s content view. Since the content view is a 
subview of the Box, the frame rectangles of Views added to the Box should reflect their 
position within the content rectangle rather than the Box’s bounds rectangle. After 
you’ve added a subview, you’ll probably want to use the sizeToFit method to adjust the 
Box’s size to accommodate its new subview. Returns self. 

See also: - sizeToFit 

awake 

- awake 

Lays out the Box during the unarchiving process so that it can be displayed. You should 
never directly invoke this method. 

borderType 

- (int)borderType 

Returns the Box’s border type, which is NX_LINE, NX_GROOVE, NX_BEZEL, or 
NXJMOBORDER. 

See also: - setBorderType: 


cell 

- cell 

Returns the cell used to display the title of the Box. 

content View 

- contentView 

Returns the Box’s content view. 

See also: - setContentView: 
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drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

Draws the Box. You never invoke this method directly; it’s invoked from Box’s 
inherited display methods. Returns self. 

See also: - display (View) 

font 

- font 

Returns the id of the font object used to draw the title of the Box. 

See also: -setFont: 

free 

- free 

Releases the storage for the Box and all its subviews. 

See also: - free (View) 

getOffsets: 

- getOffsets: (NXSize *)theSize 

Gets the horizontal and vertical distances between the border of the Box and the content 
view, and places them in the structure indicated by theSize. Returns self. 

See also: - setOffsets:: 
initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes the Box, which must be a newly allocated Box instance. The Box’s frame 
rectangle is made equivalent to that pointed to by frameRect. The title is “Title,” the 
border type is NX_GROOVE, the title position is NX_ATTOP, and the offsets are 
5.0-by-5.0. The Box’s content view is created, but it has no size; you will probably 
want to set its size with the sizeToFit method. This method is the designated initializer 
for the Box class, and can be used to initialize a Box allocated from your own zone. 
Returns self. 

See also: - initFrame (View), + alloc (Object), + allocFromZone: (Object), 

- addSubview:, - sizeToFit 
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read: 


- read:(NXTypedStream *)stream 

Reads the Box from the typed stream stream. Returns self. 

See also: - write: 

setBorderType: 

- setBorderType:(int)<37yp<? 

Sets the border type to aType, which must be NXJLINE, NX_GROOVE, NX_BEZEL, 
or NX_NOBORDER. The default is NX_GROOVE. Returns self. 

See also: - borderType 

setContentView: 

- setContentView:^ View 

Replaces the Box’s content view with aView and recalculates the size of the Box based 
on the size of the new content view. The old content view is returned. 

See also: - addSubview:, - contentView, - sizeToFit 

setFont: 

- setFont ifontObj 

Sets the title’s font to fontObj. By default, the title will be displayed using 12-point 
Helvetica. 

See also: + newFont:size: (Font) 

setF rameF romContentFr ame: 

- setFrameFromContentFrame: (const NXRect *)contentFrame 

Resizes the Box so that its content view lies on contentFrame. contentFrame is in the 
coordinate system of the Box’s superview. Returns self. 

See also: - setOffsets::, - setFrame: (View) 
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setOffsets:: 

- setOffsets :(NXCoord)w :(NXCoord)/z 

Sets the horizontal and vertical distance between the border of the Box and its content 
view, w refers to the horizontal offset and h refers to the vertical offset; these offsets 
are applied to both sides of the content view. After changing the offsets, you’ll want to 
resize the Box using the setFrameFromContentFrame: method. This method returns 
self. In the following example, the offsets are modified but the content view’s size and 
location within the Box’s superview remain unchanged: 


id contentView; 

NXRect contentRect; 

NXCoord w = 10.0, h = 10.0; 

contentView = [myBox contentView]; 

[contentView getFrame:ScontentRect]; 

[myBox convertRectToSuperview:ScontentRect]; 

[myBox setOffsets:w :h]; 

[myBox setFrameFromContentFrame:&contentRect]; 


See also: - setFrameFromContentFrame:, - convertRectToSuperview: (View) 


setTitle: 

- setTitle: (const char *)aString 

Sets the title to aString. The default title is “Title.” Returns self. 
See also: - setFont: 


setTitlePosition: 

- setTitlePosition : (int )aPosition 


Sets the title position to aPosition, which can be one of the values listed in the following 
table. The default position is NX_ATTOP. Returns self. 


aPosition value 

NX_NOTITLE 
NX_AB OVETOP 
NX_ATTOP 
NXJBELOWTOP 
NX_AB OVEB OTTOM 
NX_ATB OTTOM 

nx_belowbottom 


Meaning 

The Box has no title 

Title positioned above the Box’s top border 
Title positioned within the Box’s top border 
Title positioned below the Box’s top border 
Title positioned above the Box’s bottom border 
Title positioned within the Box’s bottom border 
Title positioned below the Box’s bottom border 
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sizeTo:: 


- sizeTo: (NXCoord)w/J^ :(NXCoord )height 

Resizes the Box to width and height. The Box is laid out to fit inside this new boundary. 
If the new width or height of the Box is too small to accommodate its border or offsets, 
the respective dimension of the content view will be zero. Returns self. 

See also: - setFrameFromContentFrame:, - getOffsets: 

sizeToFit 

- sizeToFit 

Calculates the appropriate size for the Box’s content rectangle so that it just encloses 
all the content view’s subviews. A setFrameFromContentFrame: message is then 
sent to resize the Box to enclose the new content rectangle. Returns self. 

See also: - setFrameFromContentFrame: 

title 

- (const char *)title 
Returns the title of the Box. 

See also: - setTitle: 


titlePosition 

- (int)titlePosition 

Returns an integer representing the title position. See the description for 
setTitlePosition: for possible title position values. 

See also: - setTitlePosition: 

write: 

- write :(NXTypedStream *)stream 

Writes the receiving Box to the typed stream stream. Returns self. 

See also: - read: 
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Button 


INHERITS FROM Control: View : Responder : Object 

DECLARED IN appkit/Button.h 

CLASS DESCRIPTION 

A Button is a Control subclass that intercepts mouse-down events and sends an action 
message to a target object whenever the Button is pressed. 

Button essentially provides the Control view needed to display a ButtonCell object. 
Most of its methods simply delegate to the same method in ButtonCell. To change the 
look or behavior of a Button, create a subclass of ButtonCell and use the method 
setCellClass: to get the Button class to use it. 

Buttons can display any NXImage object. The icon methods altlcon, icon, 
setAltlcon:, and setlcon: are provided for use with named images. The corresponding 
image methods altlmage, image, setAltlmage:, and setlmage: are provided for use 
with the ids of image objects. 

The initFrame:icon:tag:target:aetion:key:enabled: method is the designated 
initializer for Buttons that display icons. Buttons that display text have the designated 
initializer initFrame:text:tag:target:action:key:enabled:. Override one of these 
methods if you create a subclass of Button that performs its own initialization. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Inherited from Control 

int 

tag; 


id 

cell; 


struct _conFlags 

conFlags; 

Declared in Button 

(none) 
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METHOD TYPES 


Setting Button’s Cell Class + setCellClass: 

Initializing a Button Instance - init 

- initFrame: 

- initFrame: icon:tag '.target: action :key: enabled: 

- initFrame:title:tag:target:action:key:enabled: 

- setType: 

- setState: 

- state 

- getPeriodicDelay:andInterval: 

- setPeriodicDelay:andInterval: 

- altTitle 

- setAltTitle: 

- setTitle: 

- setTitleNoCopy: 

- title 

- altlcon 

- altlmage 

- icon 

- image 

- iconPosition 

- setAltlcon: 

- set Altlmage: 

- setlcon: 

- setlmage: 

- setlcon position: 

- setlconPosition: 

Modifying Graphic Attributes - isBordered 

~ isTransparent 

- setBordered: 

- setTransparent: 

Displaying - display 

- highlight: 

Handling Events and Action Messages 

- acceptsFirstMouse 

- keyEquivalent 

- performClick: 

- performKeyEquivalent: 

- setKeyEquivalent: 


Setting the Button Type 
Setting the State 

Setting Button Repeat 

Modifying the Title 

Modifying the Icon 
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Setting the Sound 


- setSound: 

- sound 


CLASS METHODS 

setCellClass: 

+ setCellClass iclassld 

Initializes the Button to work with a subclass of ButtonCell. The classld will usually 
be the value returned by the message [myButtonCell class], where myButtonCell is an 
instance of the subclass. Returns self. 

INSTANCE METHODS 

acceptsFirstMouse 

- (BOOL)acceptsFirstMouse 

Returns YES. Buttons always accept the mouse-down event that activates a Window. 

altlcon 

- (const char *)altIcon 

Returns the Button’s alternate icon by name. This icon will appear on the Button when 
it’s in its alternate state. 

altlmage 

- altlmage 

Returns the Button’s alternate icon by id. This image will appear on the Button when 
it’s in its alternate state. 

altTitle 

- (const char *)altTitle 

Returns the current value of the Button’s alternate title. This is the string that appears 
on the Button when it’s in its alternate state. 

display 

- display 

Overridden from View so that displayFromOpaqueAncestor::: is called if the Button 
has some non-opaque parts. Returns self. 
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getPer iodicDelay: andlnterval: 

- getPeriodicDelay: (float *)delay andlnterval: (float *) interval 

This method returns self explicitly and two values by reference, delay returns the 
amount of time (in seconds) that a continuous button will pause before starting to 
periodically send action messages to the target object, interval returns the amount of 
time (also in seconds) between those messages. 

See also: - setContinuous: (Control), - setPeriodicDelay:andlnterval: 
highlight: 

- highlight:(BOOL)/7<2g 

If the highlighted flag of the cell is not equal to flag, the Button is highlighted and the 
highlighted flag of the cell is set to flag. Issues a flush Window after highlighting the 
Button. Returns self. 

See also: - performClick: 
icon 

- (const char *)icon 

Returns the Button’s icon by name. 

iconPosition 

- (int)iconPosition 

Returns a constant representing the position of the icon on the Button. See 
setlconPosition: for the list of position constants. 

image 

- image 

Returns the id of the Button’s icon. 

See also: - altlmage, - setAltlcon:, - setAltlmage: 


init 


- init 


Initializes and returns the receiver, a new Button instance. The new instance displays 
the word “Button” and has no icon associated with it. You usually invoke 
initFrame:{title,icon }:tag:target:action:key:enab!ed: to initialize a Button. 
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initFrame: 


- initFrame: (const NXRect *)frameRect 

Initializes and returns the receiver, a new Button instance, with default parameters in 
the given frame. The default title is “Button,” the default action is NULL and the 
default target is nil. You usually invoke 

initFrame:{title,icon}:tag:target:action:key:enabled: to initialize a Button. 


initFrame:icon:tag:target:action:key:enabled: 

- initFrame .‘(const NXRect *)frameRect 
icon: (const char *)aString 
tag:(mt)anlnt 
tavgeUanObject 
action:(SEL)aSelector 
key:(unsigned shon)charCode 
enabled: (BOOL )flag 

Initializes and returns the receiver, a new Button instance that displays an icon. The 
arguments and operation of this method are exactly like those of 
initFrame:title:tag:target:action:key:enabled:, except that the Button displays the 
named icon represented by aString rather than displaying a text string. This method is 
the designated initializer for Buttons that display icons. 


initFrame:title:tag:target:action:key:enabled: 

- initFrame: (const NXRect *)frameRect 
title: (const char *)aString 
tag:(int)anlnt 
targeUanObject 
action:(SEL)aSelector 
key:(unsigned short )charCode 
enabled : (BOOL )flag 

Initializes and returns the receiver, a new Button instance that displays a text string. 
anlnt is a unique tag to identify your Button View. frameRect is the rectangle the 
Button will occupy in its superview’s coordinates. aString contains the title for the 
Button. anObject is the target that will be notified via the action message aSelector 
when the Button is successfully pressed. If anObject is nil, the target will default to the 
Button’s superview. aSelector should be a valid selector. charCode is the key 
equivalent for this Button, flag determines whether your Button is initially enabled. 
This method is the designated initializer for Buttons that display text. 
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isBordered 


- (BOOL)isBordered 

Returns YES if the Button has a border, NO otherwise. 

See also: - setBordered: 

isTransparent 

- (BOOL)isTransparent 

Returns YES if the Button is transparent, NO otherwise. 

See also: - setTransparent: 

keyEquivalent 

- (unsigned shortjkeyEquivalent 

Returns the key equivalent character of the Button. 

See also: - performKeyEquivalent: 

performCiick: 

- performClickrsercder 

Highlights the Button, sends its action message to the target object, then unhighlights 
the Button. Invoke this method when you want the Button to behave exactly as if the 
user had clicked it with the mouse. 

performKeyEquivalent: 

- (BOOL)performKeyEquivalent:(NXEvent *)theEvent 

Simulates the user clicking the Button and returns YES if the character in the event 
record matches the Button’s key equivalent. Otherwise, does nothing and returns NO. 

See also: - keyEquivalent 
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setAltlcon: 


- setAltlcon: (const char *)iconName 

Sets the Button’s alternate icon by name; iconName is the name of an image to be 
displayed. Does not display the Button even if autodisplay is on. 

See also: - setlcon: 

setAltlmage: 

- setAltlmagena/t/mage 

Sets the Button’s alternate icon by id; altlmage is the id of the image to be displayed. 
Does not display the Button even if autodisplay is on. 

See also: - setlmage: 
setAltTitle: 

- setAltTitle: (const char *)aString 

Sets the alternate title of your Button to aString, the title that will display when the 
Button is clicked. Does not display the Button even if autodisplay is on. 

setBordered: 

- setBordered:(BOOL)/7<zg 

If flag is YES, the Button displays a border; if NO, no border is displayed. This method 
redraws the Button if the bordered state is changed. Returns self. 

setlcon: 

- setlcon: (const char *)iconName 

Sets the Button’s icon by name; iconName is the name of an image to be displayed. 
Returns self. 

See also: - getBitmapFor: (Bitmap) 
setlcon: position: 

- setlcon: (const char *)iconName position : (int)aPosition 

Combines setlcon: and setlconPosition: into one message. Returns self. 
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setlconPosition: 


- setlconPosition : (int )aPosition 


Sets the position of the icon when a Button simultaneously displays both text and an 
icon. aPosition can be one of the following constants: 


NX_TITLEONLY 

NXJCONONLY 

NX_ICONLEFT 

NXJCONRIGHT 

NX_ICONBELOW 

NX_ICONABOVE 

NX_ICONOVERLAPS 


title only (no icon on the Button) 
icon only (no text on the Button) 
icon is to the left of the text 
icon is to the right of the text 
icon is below the text 
icon is above the text 
icon and text overlap 


If the position is top or bottom, the alignment of the text will be set to 
NX_CENTERED. This behavior can be overridden with a subsequent setAlignment:. 
Returns self. 


setlmage: 

- setlmage:image 

Sets the Button’s icon by id; image is the id of the image to be displayed. Returns self. 
See also: + fmdImageNamed:(NXImage) 

setKey Equivalent: 

- setKeyEquivalent: (unsigned short )charCode 

Sets the key equivalent character of the Button. Returns self. 

See also: - keyEquivalent, - performKeyEquivalent: 

setPeriodicDelay:andInterval: 

- setPeriodicDelay:(float)de/ay andIntervaI:(float)mre/'va/ 

Sets two values that are in effect if the Button is set to continuously send the action 
message to the target object while tracking the mouse, delay is the amount of time (in 
seconds) that a continuous button will pause before starting to periodically send action 
messages to the target object, interval is the amount of time (also in seconds) between 
those messages. Returns self. 

See also: - getPeriodicDelayiandlnterval:, - setContinuous(Control) 
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setSound: 


- setSound isoundObj 

Sets the sound played when the Button is pressed. Returns self. 
setState: 

- setState:(int)vtf/we 

Sets the Button’s state to value and redraws the Button. Returns self. 

setTitle: 

- setTitle: (const char *)aString 

Sets the title of the Button to aString. Returns self. 

setTitleNoCopy: 

- setTitleNoCopy:(const char *)aString 

Similar to setTitle: but does not make a copy of aString. Returns self. 

setTransparent: 

- setTransparent: (BOOL )flag 

Sets whether the Button is transparent. A transparent Button tracks the mouse and 
sends its action, but it doesn’t draw anything. Returns self. 
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setType: 

- setType :(int)d7ype 

Sets the way the Button shows its state and highlighting, and returns self. aType can be 
one of five constants: 

NX_MOMENTARYPUSH (the default). States 0 and 1 are displayed in the same 
manner. Highlighting is shown by the Button’s “pushing in” to the screen. 

NX_MOMENTARYCHANGE. States 0 and 1 look identical. When the Button is 
highlighted, the alternate icon or alternate text will be displayed. The miniaturize 
Button in the window frame is a good example of this type of Button. 

NX_PUSHONPUSHOFF. State 1 differs from state 0 by the fact that different colors 
are used. Highlighting is achieved by “pushing in.” 

NX_TOGGLE. State 1 uses the altContents and/or altlcon. Highlighting is performed 
by “pushing in.” 

NX_S WITCH. A variant of NX_TOGGLE that has no border, and that has a default 
icon called “switch.” 

sound 

- sound 

Returns the sound played when the button is pressed. 

state 

- (int)state 

Returns the Button’s state (0 or 1). 

title 

- (const char *)title 

Returns a pointer to the current string value of the Button’s title. 
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ButtonCell 


INHERITS FROM ActionCell: Cell: Object 

DECLARED IN appkit/ButtonCell.h 

CLASS DESCRIPTION 

The ButtonCell class is a subclass of Cell that is used to implement Button. Different 
modes of button operation are distinguished according to the values of the changeXXX 
and lightByXXX bitfields. 

changeXXX refers to what changes when the state changes. Thus, if changeGray is 
set, then, when a button is in state 1, all light gray areas in the button become white, and 
all white areas become light gray. If changeBackground is set, then the background 
in state 1 is white instead of the default light gray used in state 0. If changeContents 
is set, then altContents and/or icon.bmap.alternate are used to draw the button when it 
is in state 1. If both changeBackground and changeGray are set, then the ButtonCell 
will use changeGray unless the ButtonCell has an icon and alpha values, in which case 
it will use changeBackground. The lightByXXX flags have similar meanings, but are 
used when the button is pressed to highlight the button. The pushln flag is used to 
determine whether the button appears to “push in” to the screen when pressed. This 
only has meaning when the bordered flag is set. 

For all ButtonCells, the “default” icon is the keyEquivalent for the button. Therefore, 
if you want the button to display its keyEquivalent, just use setlconPosition: to 
determine where on the button the keyEquivalent should appear. MenuCells use this, 
for example (by issuing a setIconPosition:NX_ICONRIGHT). If you set an icon (or 
an altlcon) for the button, then the icon will be displayed instead of the keyEquivalent, 
so if you want the keyEquivalent, don’t invoke setlcon:! 

ButtonCells can display any type of image. The icon methods altlcon, icon, 
setAltlcon:, and setlcon: work with named images. The corresponding image 
methods altlmage, image, setAltlmage:, and setlmage: work with ids of image 
objects. 

The initlconCell: method is the designated initializer for ButtonCells that display 
icons. The initTextCell: method is the designated initializer for ButtonCells that 
display text. Override one of these methods if you create a subclass of ButtonCell that 
does its own initialization. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Cell 

char 

^contents; 


id 

support; 


struct _cFlagsl 

cFlagsl; 


struct _cFlags2 

cFlags2; 

Inherited from ActionCell 

int 

tag; 


id 

target; 


SEL 

action; 

Declared in ButtonCell 

char 

union _icon { 
struct _bmap { 

*altContents; 


id 

normal; 


id 

alternate; 


} 

struct _ke { 

bmap; 


id 

font; 


float 

descent; 


} 

ke; 


} 

icon; 


id 

sound; 


struct _bcFlagsl { 



unsigned int 

pushlml; 


unsigned int 

changeContents: 1; 


unsigned int 

changeBackground: 1; 


unsigned int 

changeGray:l; 


unsigned int 

lightByContents:l; 


unsigned int 

lightByBackground: 1; 


unsigned int 

lightByGrayrl; 


unsigned int 

hasAlpharl; 


unsigned int 

bordered: 1; 


unsigned int 

iconOverlaps:l; 


unsigned int 

horizontal: 1; 


unsigned int 

bottomOrLeft:l; 


unsigned int 

iconAndText: 1; 


unsigned int 

lastState:l; 


unsigned int 

iconSizeDiff:l; 


unsigned int 

iconlsKeyEquivalent: 1; 


} 

struct _bcFlags2 { 

bcFlagsl; 


unsigned int 

key Equivalent: 8; 


unsigned int 

transparent: 1; 


} 

bcFlags2; 


unsigned short 

periodicDelay; 


unsigned short 

periodiclnterval; 
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altContents 


Alternate contents used instead of contents in 
certain state configurations. 


bmap.normal 

Name of the icon for this button. 

bmap. alternate 

Name of the alternate icon. 

ke.font 

Font used to draw the key equivalent. 

ke.descent 

The descent of descenders in the key equivalent 
font. 

sound 

The button’s sound. 

bcFlagsl.pushln 

Button appears to push into the screen when 
pressed. 

bcFlags 1 .changeContents 

Show alternate state by using alternate contents. 

bcFlags 1 .changeBackground 

Show alternate state by changing the background. 

bcFlags 1 .changeGray 

Show alternate state by inverting the button. 

bcFlags 1 .lightByContents 

Show highlighting by using alternate contents. 

bcFlags 1 .lightByBackground 

Show highlighting by changing the background. 

bcFlags 1 .lightByGray 

Show highlighting by inverting the button. 

bcFlags 1 .has Alpha 

Icon has alpha values. 

bcFlags 1 .bordered 

Button has border. 

bcFlags 1 .iconOverlaps 

Icon overlaps text. 

bcFlags 1 .horizontal 

Icon to side of text. 

bcFlags 1 .bottomOrLeft 

Icon on left or bottom. 

bcFlags 1 .iconAndText 

Button has icon and text. 

bcFlags l.lastState 

Last state drawn. 

bcFlags 1. iconS izeDiff 

Alternate icon is a different size than the normal 
icon. 

bcFlags 1 .iconlsKeyEquivalent 

The icon is the key equivalent. 

bcFlags2.keyEquivalent 

The key equivalent. 
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bcFlags2.transparent 

Whether to draw. 

periodicDelay 

The delay before sending the first send by a 
continuous button. 

periodiclnterval 

The interval at which a continuous button sends 
its action. 

METHOD TYPES 


Copying, Initializing and Freeing a ButtonCell 

- copyFromZone 

- init 

- initlconCell: 

- initTextCell: 

- free 

Determining Component Sizes 

- calcCellSize:inRect: 

- getDrawRect: 

- getlconRect: 

- getTitleRect: 

Modifying the Title 

- altTitle 

- setAltTitle: 

- setFont: 

- setTitle: 

- setTitleNoCopy: 

- title 

Modifying the Icon 

- altlcon 

- altlmage 

- icon 

- image 

- iconPosition 

- setAltlcon: 

- set Altlmage: 

- setlcon: 

- setlmage: 

- setlconPosition: 

Modifying the Sound 

- setSound: 

- sound 
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Setting the State 

- double Value 

- float Value 

- intValue 

- setDoubleValue: 

- setFloatValue: 

- setlnt Value: 

- setStringValue: 

- setStringValueNoCopy: 

- string Value 

Setting the Button Repeat 

- getPeriodicDelay:andInterval: 

- setPeriodicDelay:andInterval: 

Tracking the Mouse 

- trackMouse:inRect:ofView: 

Setting the Key Equivalent 

- keyEquivalent 

- setKeyEquivalent: 

- setKeyEquivalentFont: 

- setKeyEquivalentFont:size: 

Setting Parameters 

- getParameter: 

- setParametento: 

Modifying Graphic Attributes 

- highlightsBy 

- isBordered 

- isOpaque 

- isTransparent 

- setBordered: 

- setHighlightsBy: 

- setShowsStateBy: 

- setTransparent: 

- setType: 

- showsStateBy 

Simulating a Click 

- performClick: 

Displaying 

- drawInside:inView: 

- drawSelf:inView: 

- highlight:inView:lit: 

Archiving 

- read: 

- write: 
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INSTANCE METHODS 


altlcon 

- (const char *)altIcon 

Returns the ButtonCelTs alternate icon by name. This icon will appear on the Button 
when it is in its alternate state. If there is no alternate icon, it returns NULL. This is 
the icon that will be displayed if the iconPosition is not NX_TITLEONLY and the 
changeContents or lightByContents flag is set. 

altlmage 

- altlmage 

Returns the ButtonCelTs alternate icon by id. This image will appear on the Button 
when it is in its alternate state. If there is no alternate image, it returns nil. This is the 
image that will be displayed if the iconPosition is not NX_TITLEONLY and the 
changeContents or lightByContents flag is set. 

altTitle 

- (const char *)altTitle 

Returns the ButtonCelTs alternate title. This is the text string that will appear on the 
button if the iconPosition is not NXJCONONLY and the changeContents or 
lightByContents flag is set. 

calcCellSize:inRect: 

- calcCellSize:(NXSize *)theSize inRect:(const NXRect *)aRect 

Returns, by reference, the minimum width and height required for displaying the button 
in aRect. The computation is done as follows: 

1. The size of the contents instance variable is computed. 

2. The size of the altContents is computed. 

3. The maximum width and height are set in theSize. 

4. If the button has an additional icon, its width and height are calculated; if either is 
bigger than the contents size, the size is increased to accommodate the icon. 

5. If the button has a border, then the width and the height are incremented by the 
border width. 
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copyFromZone 

- copyFromZone :(NXZone *)zone 

Allocates, initializes, and returns a copy of the ButtonCell. Allocates the copy from 
zone. 

double Value 

- (double)double Value 

Returns the ButtonCell’s state cast as a double (0.0 or 1.0). 

dr awlnside: in V ie w: 

- drawlnside: (const NXRect *)aRect inView icontrolView 

Draws the inside of the ButtonCell (the text and the icon and their background, but not 
the bezel). This method is called by drawSelf:inView: and by the Control classes’ 
drawCelllnside: method. It is provided so that when a ButtonCell’s state is set (via 
setState:, setlntValue:, and others), a minimal update of the ButtonCell’s visual 
appearance can occur. If you subclass ButtonCell and override drawSelfrinView: you 
MUST override this method as well (however, you are free to override only this method 
and not drawSelf:inView: as long as your subclass draws inside the same area as 
ButtonCell does). Returns self. 

See also: - drawInsideiinView: (Cell) 
drawSelf: in View: 

- drawSelf: (const NXRect *)cellFrame inView icontrolView 

Displays the ButtonCell in the given rectangle of the given view. Focus must be locked 
on controlView. It draws the border of the ButtonCell if necessary, then calls 
drawInside:inView:. Returns self. 

float Value 

- (float)float Value 

Returns the ButtonCell’s state cast as a float (0.0 or 1.0). 


free 


- free 

Disposes of the memory used by the ButtonCell and returns nil. 
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getDrawRect: 

- getDrawRect:(NXRect *)theRect 


Returns self and, by reference, the bounds of the area into which the text and/or icon 
will be drawn. You must pass the bounds of the ButtonCell in theRect (the same bounds 
passed to drawSelf:inView:). It assumes that the ButtonCell is being drawn in a 
flipped view. 


getlconRect: 

- getlconRect: (NXRect *)theRect 


Returns self and, by reference, the bounds of the area into which the icon of the 
ButtonCell will be drawn. If the button has no icon, then theRect will not be touched. 
You must pass the bounds of the ButtonCell in theRect (the same bounds passed to 
drawSelfiinView:). It assumes that the ButtonCell is being drawn in a flipped view. 


getParameter: 

- (int)getParameter:(int)< 2 P< 2 rameter 


Returns the state of a number of frequently accessed flags for a ButtonCell. The 
following constants correspond to the different flags: 


NX_CELLDISABLED 

NX_CELLSTATE 

NX.CELLHIGHLIGHTED 

NX_CELLEDITABLE 

NX_CHANGECONTENTS 

NX_CHANGEBACKGROUND 

NX_CHANGEGRAY 

NX_LIGHTB Y CONTENTS 

NX JLIGHTB YB ACKGROUND 

NX_LIGHTB Y GRAY 

NX_PUSHIN 

NX_OVERLAPPINGICON 

NXJCONHORIZONTAL 

NX_ICONONLEFTORBOTTOM 

NXJCONISKEYEQUIVALENT 


You don’t normally invoke this method since all of these flags are available via normal 
querying methods (e.g., isEnabled, highlightsBy:, etc.). 
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getPer iodicDelay: andlnter val: 

- getPeriodicDelay: (float *)delay andlnterval: (float *)interval 

Returns two values: The amount of time (in seconds) that a continuous button will 
pause before starting to periodically send action messages to the target object, and the 
interval (also in seconds) at which those messages are sent. Returns self. 

See also: - setContinuous: (Cell), - setPeriodicDelay:andlnterval: 
getTitleRect: 

- getTitleRect: (NXRect *)theRect 

Returns self and, by reference, a copy of the bounds of the area into which the text of 
the ButtonCell will be drawn. You must pass the bounds of the ButtonCell in theRect 
(the same bounds passed to drawSelf:inView:). It assumes that the ButtonCell is being 
drawn in a flipped view. 


highlight:inView:lit: 

- highlight: (const NXRect *)cellFrame 

in View icontrolView 
lit:(BOOL )flag 

Highlights the ButtonCell if its highlighted flag is not equal to flag. You must 
lockFocus on controlView before calling this method. If possible, this method tries to 
use NXHighlightRect (i.e., if the button is not pushln and changeContents and 
lightByContents are not set). If it cannot use NXHighlightRect, then it simply calls 
drawSelf:inView: or drawInside:inView: dependent upon whether the border of the 
button is involved in the highlighting process (e.g., in a pushln button). Does nothing 
if the button is disabled or transparent. Returns self. 

highlightsBy 

- (int)highlightsBy 

Returns the logical OR of one or more flags that indicate the way the ButtonCell 
highlights when the button is pressed. See setHighlightsBy: for the list of flags. 

icon 

- (const char *)icon 

Returns the ButtonCell’s icon by name.. If there is no icon displayed in the ButtonCell, 
or if the icon is the key equivalent, then it returns NULL. 

See also: - setlcon: 
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iconPosition 


- (int)iconPosition 

Returns the position of the ButtonCell’s icon. See setlconPosition: for the valid 
positions. The default is NX_TITLEONLY if the ButtonCell is created with 
newTextCell: or NX_ICONONLY if created with newIconCell:. 

image 

- image 

Returns the ButtonCell’s icon by id. If there is no image displayed in the ButtonCell, 
or if the image is the key equivalent, then it returns nil. 

See also: - setlmage: 


init 


- init 


Initializes and returns the receiver, a new ButtonCell, as a text cell with the word 
“Button” on it. 

initlconCell: 

- initlconCell: (const char *)iconName 

Initializes and returns the receiver, a new ButtonCell, with default size. By default, the 
ButtonCell is bordered and is pushln. None of the changeXXX flags is set. The 
lightByGray and lightByBackground flags are set. This means that, when pressed, 
the button will perform NXHighlightRect() if the icon has no alpha or will change the 
background (from light gray to white) if the icon does have alpha values. An icon is a 
named NXImage; see the NXImage class for details. This is the designated initializer 
for ButtonCells that display icons. 

See also: - findlmageNamed: (NXImage) 
initTextCell: 

- initTextCell: (const char *)aString 

Initializes the receiver, a new ButtonCell, with default size, font, title, and centered 
alignment. By default, the ButtonCell is bordered and is pushln. None of the 
changeXXX is set and the button will “light up” when pressed (lightByGray and 
lightByBackground are set). This is the designated initializer for ButtonCells that 
display text. 


2-132 Chapter 2: Class Specifications 



int Value 


- (int)intValue 

Returns the ButtonCell’s state (0 or 1). 

isBordered 

- (BOOL)isBordered 

Returns YES if the button has a border, NO if not. 

isOpaque 

- (BOOL)isOpaque 

Returns YES if drawing the ButtonCell touches all the bits in its frame, NO if not. The 
ButtonCell is opaque if it is not transparent and if it has a border. 

isTransparent 

- (BOOL)isTransparent 

Returns YES if the ButtonCell is transparent, NO if not. 

See also: - setTransparent: 

keyEquivalent 

- (unsigned short)keyEquivalent 

Returns the key equivalent character of the ButtonCell. 

performClick: 

- performClick ’.sender 

If this ButtonCell is contained in a Control, then invoking this method causes the 
ButtonCell to act exactly as if the user had clicked the button. 

read: 

- read:(NXTypedStream *)stream 

Reads the ButtonCell from the typed stream stream. 
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setAltlcon: 


- setAltlcon: (const char *)iconName 

Sets the ButtonCell’s alternate icon by name; iconName is the name of an image to be 
displayed. This icon is displayed if the changeContents or lightByContents flag is 
set; these are set by the setShowsStateBy: and setHighlightsBy: methods, 
respectively. Note that no icon will be displayed in a ButtonCell unless setlcon: or 
setlmage: is invoked (thus, setAltlcon: by itself has no affect on the appearance of the 
button). Returns self. 

See also: - setlcon: 

setAItlmage: 

- setAltImage:a/t/mage 

Sets the ButtonCell’s alternate icon by id; altlmage is the id of the image to be 
displayed. This image is displayed if the changeContents or lightByContents flag is 
set; these are set by the setShowsStateBy: and setHighlightsBy: methods, 
respectively. Note that no image will be displayed in a ButtonCell unless setlcon: or 
setlmage: is invoked (thus, setAItlmage: by itself has no effect on the appearance of 
the button). Returns self. 

See also: - setlmage: 
setAltTitle: 

- setAltTitle: (const char *)aString 

Invoke this method to set the alternate title to a copy of aString. If the ButtonCell was 
not an NX_TEXTCELL, it is automatically converted, in which case its support 
instance variable is set to the default font. If there is an icon associated with this 
ButtonCell, then the iconAndText flag is set. Returns self. 

setBordered: 

- setBordered :(BOOL)/fag 

If flag is YES, sets the ButtonCell to display a border; if flag is NO, it has none. 
Redraws the ButtonCell if its bordered status changes. Returns self. 

setDoubleValue: 

- setDoubleValue:(double)a£><?«6/e 

Sets the ButtonCell’s state to 1 if aDouble is nonzero, 0 otherwise. Returns self. 
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setFloatValue: 


- setFloatValue \{fiodA)aFloat 

Sets the ButtonCell’s state to 1 if aFloat is non-zero, 0 otherwise. Returns self. 

setFont: 

- setFontr/onfOb/ 

Sets the font to be used when displaying text. Does nothing if the cell type is not 
NX_TEXTCELL. Returns self. 

setHighlightsBy: 

- setHighlightsBy :(mt)aType 

Sets the way the button highlights itself. aType can be the logical OR of one or more 
of the following constants: 

NX_PUSHIN The button “pushes in” when pressed (default) 

NX_NONE No difference when highlighted 

NX_CONTENTS Use the alternate contents 

NX_CHANGEGRAY Light gray -> white, white -> light gray 

NX_CHANGEBACKGROUND Same as NX_CHANGEGRAY, but only 

touches background 

If you specify both NX_CHANGEGRAY and NX_CHANGEBACKGROUND, then a 
choice will be made between the two based on whether the icon of your button (if any) 
has any alpha. If it does, then NX_CHANGEBACKGROUND will be used; otherwise, 
NX_CHANGEGRAY will be used. If your button has no icon, then 
NX_CHANGEGRAY will be used. Returns self. 

setlcon: 

- setlcon:(const char *)iconName 

Sets the ButtonCell’s icon by name; iconName is the name of an image to be displayed. 
If there is no text associated with the ButtonCell, then it is converted to 
NX_ICONCELL; otherwise, the iconOverlaps flag is set. An icon is a named 
NXImage. Returns self. 

See also: - findlmageNamed: (NXImage) 
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setlconPosition: 


- setlconPosition :(mt)aPosition 

Sets the position of the icon for this ButtonCell. aPosition can be one of the following 
constants: 


NX_TITLEONLY = title only 
NXJCONONLY = icon only 
NX_ICONLEFT = icon left of the text 
NX JCONRIGHT = right of the text 
NXJCONBELOW = below the text 
NXJCONABOVE = above the text 
NX_ICONOVERLAPS = overlapping 


(iconAndText = 0, iconOverlaps = 0) 
(iconAndText = 0, iconOverlaps = 1) 
(iconAndText = 1, iconOverlaps = 0) 
(iconAndText = 1, iconOverlaps = 0) 
(iconAndText = 1, iconOverlaps = 0) 
(iconAndText = 1, iconOverlaps = 0) 
(iconAndText = 1, iconOverlaps = 1) 


If the position is top or bottom, the alignment of the text will be set to 
NX_CENTERED. This can be overridden with a subsequent setAlignment:. Returns 


self. 


setlmage: 

- setlmage:image 

Sets the ButtonCell’s icon; image is the id of an image to be displayed. Returns self. 

setlntValue: 

- setlntValue: (mi)anlnt 

Sets the ButtonCell’s state to 1 if anlnt is nonzero, 0 otherwise. Returns self. 
setKeyEquivalent: 

- setKeyEquivalent ‘.(unsigned short)charCode 

Sets the key equivalent character of the ButtonCell. The key equivalent will appear on 
the button only if there is no icon set (with setlcon: or setAltlcon:) and the 
iconPosition is not NX_TITLEONLY or NX JCONONLY or NXJCONOVERLAPS. 
The canonical way to put the key equivalent character on your button is to invoke 
setKeyEquivalent:, then invoke setlconPosition :NX_ICONRIGHT (or LEFT or 
ABOVE or BELOW). Menu entries (which inherit from ButtonCell) are usually the 
only ButtonCells with key equivalents. Returns self. 

A ButtonCell’s key equivalent can be tested by sending it a keyEquivalent message. 
See also: - keyEquivalent, - performClick: (Matrix, Button) 
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setKeyEquivalentFont: 

- setKeyEquivalentFont:/<9«?0£>/ 

Sets the font used to draw the keyEquivalent. Does nothing if there is already an icon 
associated with this ButtonCell. The default font is the same as that used to draw the 
text on the ButtonCell. Returns self. 

setKeyEqui valentF ont: size: 

- setKeyEquivalentFont: (const char *)fontName size:(float )fontSize 

Convenient form of setKeyEquivalent: that sets both the font and font size used to 
draw the keyEquivalent. Returns self. 

setParameter:to: 

- setParameter : (int)aParameter to:(int )value 

Sets the most usual flags of a ButtonCell. See getParameter: for the list of usual flags. 
You do not usually invoke this method; instead use the appropriate set... methods to set 
flags. Returns self. 

setPer iodicDelay: andlnterval: 

- setPer iodicDelay: (float )delay andlnterval: (float )interval 

This method sets two values; The amount of time (in seconds) that a continuous button 
will pause before starting to periodically send action messages to the target object, and 
the interval (also in seconds) at which those messages are sent. The maximum delay 
or interval is 60.0 seconds. Returns self. 

See also: - setContinuous: (Cell) 


Application Kit Classes: ButtonCell 


2-137 



setShowsStateBy: 

- setShowsStateBy: (mi)aType 

Sets the way the button shows its alternate state. aType should be the logical OR of one 
or more of the following constants: 


NX_PUSHIN 

NX_NONE 

NX_CONTENTS 

NX_CHANGEGRAY 

NX_CHANGEBACKGROUND 


The button “pushes in” when pressed (default) 

No difference when highlighted 

Use the alternate contents 

Light gray -> white, white -> light gray 

Same as NX_CHANGEGRAY, but only 

touches background 


If you specify both NX_CHANGEGRAY and NX_CHANGEBACKGROUND, then a 
choice will be made between the two based on whether the icon of your button (if any) 
has any alpha. If it does, then NX_CHANGEBACKGROUND will be used, else 
NX_CHANGEGRAY. If your button has no icon, then NX_CHANGEGRAY will be 
used. Returns self. 


setSound: 

- setSound laSound 


Sets the sound that will be played when the mouse goes down in the ButtonCell. If you 
use a sound on your button, you must link your application against the soundkit. 
Returns self. 


setStringValue: 

- setStringValue: (const char *)aString 

Sets the state of the ButtonCell. If aString is a non-null string, the state is set to 1; if 
aString is null, the state is set to 0. Returns self. 

setStringValueNoCopy: 

- setString ValueNoCopy:(const char *)aString 


Same as setStringValue:. 


setTitle: 

- setTitle: (const char *)aString 


Sets the text that is displayed on the button to aString. If there is already an icon 
associated with the button, then the iconAndText flag is set to YES. Returns self. 
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setTitleNoCopy: 

- setTitleNoCopy:(const char *)aString 

Similar to setTitle: but does not make a copy of aString. Returns self. 

setTransparent: 

- setTransparent :(BOOL)/fag 

Sets whether the ButtonCell is transparent. A transparent button never draws anything, 
but it does track the mouse and send its action normally. This method is useful for 
sensitizing an area on the screen so that an action gets sent to a target when the area 
receives a mouse click. Returns self. 


setType: 

- setType:(int )aType 

Sets standard button types. The ButtonCell does not record the type directly; instead, 
this method sets the changeXXX and lightByXXX flags appropriately. The 
NX_SWITCH and NX_RADIOBUTTON types also set the icon to the default icon for 
that type of button (only if there is not already an icon set). aType can be one of the 
following constants: 

NX_MOMENTARYPUSH 

NX_MOMENTARY CHANGE 

NXJPUSHONPUSHOFF 

NX_TOGGLE 

NX_SWITCH 

NX_RADIOBUTTON 

This method is invoked by Button’s setType: method. It is very useful for creating 
prototype cells in a matrix of radio buttons. Returns self. 

See also: - setType: (Button) 

showsStateBy 

- (int)showsStateBy 

Returns flags reflecting the way that the button shows its alternate state. See 
setShowsStateBy: for list of appropriate flags. Returns self. 

sound 

- sound 

Returns the sound object that is sent a play message on a mouse-down event in the 
ButtonCell. 


See also: - setSound: 
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stringValue 

- (const char *)stringValue 

Returns the ButtonCell’s state as a string. If the state is 1, (empty string) is returned, 
otherwise, NULL is returned. This is an unusual method to invoke (since the 
stringValue of a button doesn’t make much sense) and is included only for 
completeness. 

title 

- (const char *)title 

Returns ButtonCell’s text if the receiving ButtonCell displays any text; otherwise it 
returns NULL. 

trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent *)theEvent 

inRect:(const NXRect *)cellFrame 
ofWiew icontrolView 

Tracks the mouse by starting the sound (if any) and calling 

[super trackMouseitheEvent mReeticellFrame ofYiewicontrolView]. Returns YES if 
the mouse button goes up with the cursor in the cell, NO otherwise. 

See also: - trackMouse:inReet:ofView: (Cell) 
write: 

- write:(NXTypedStream *)stream 

Writes the receiving ButtonCell to the typed stream stream. Returns self. 


CONSTANTS AND DEFINED TYPES 


/* Button Types */ 

#define NXJMOMENTARYPUSH 0 
#define NX_PUSHONPUSHOFF 1 
#define NXJIOGGLE 2 
#define NX_SWITCH 3 
#define NX_RADIOBUTTON 4 
#define NX MOMENTARYCHANGE 5 
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INHERITS FROM 


Object 


DECLARED IN appkit/Cell.h 

CLASS DESCRIPTION 

Cell is an abstract super class that provides many useful functions needed for displaying 
text or icons without the overhead of a full View subclass. In particular, it provides 
most of the functionality of a Text class by providing access to a shared Text object that 
can be used by all instances of Cell in an Application. Cell is used heavily by the 
Control classes to implement their internal workings. Some subclasses of Control 
(notably Matrix) allow multiple Cells to be grouped and act together in some 
cooperative manner. Thus, with a Matrix, a group of radio buttons can be implemented 
without needing a View for each button (and without needing a Text object for the text 
on each button). Cells are also extremely useful for placing titles or icons at will in a 
custom subclass of View. 

The Cell class provides primitives for displaying text or an icon, editing text, formatting 
floating point numbers, maintaining state, highlighting, and tracking the mouse. It has 
several subclasses: SelectionCell, NXBrowserCell, and ActionCell (which in turn has 
the subclasses ButtonCell, SliderCell, TextFieldCell, and FormCell). Cell’s 
trackMouse:inRect:ofView: method supports the target object and action method 
used to implement controls. However, Cell implements these features abstractly, 
deferring the details of implementation to ActionCell. 

The initlconCell: method is the designated initializer for Cells that display icons. The 
initTextCell: method is the designated initializer for Cells that display text. Override 
one of these methods if you implement a subclass of Cell that performs its own 
initialization. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in Cell 

char 

^contents; 


id 

struct _cFlagsl { 

support; 


unsigned int 

state:1; 


unsigned int 

highlighted: 1; 


unsigned int 

disabled: 1; 


unsigned int 

editable: 1; 


unsigned int 

type: 2; 


unsigned int 

freeText:l; 


unsigned int 

alignment^; 


unsigned int 

bordered: 1; 


unsigned int 

bezeled:l; 


unsigned int 

selectable: 1; 


unsigned int 

scrollable: 1; 


unsigned int 

entry Type: 3; 


} 

struct _cFlags2 { 

cFlagsl; 


unsigned int 

continuous:!; 


unsigned int 

actOnMouseDown: 1; 


unsigned int 

floatLeft:4; 


unsigned int 

floatRight:4; 


unsigned int 

autoRange:l; 


unsigned int 

actOnMouseDragged: 1; 


unsigned int 

noWrap: 1; 


unsigned int 

dontActOnMouseUp: 1; 


} 

cFlags2; 


contents 

String for a TextCell, name of the icon for an 
IconCell. 

support 

Font for TextCell, NXImage for IconCell. 

cFlags l.state 

Current state of the Cell (0 or 1). 

cFlagsl .highlighted 

Whether Cell is highlighted. 

cFlagsl.disabled 

Whether Cell is disabled. 

cFlagsl.editable 

Whether text in the Cell is editable. 

cFlagsl. type 

NULLCELL, TEXTCELL, or ICONCELL. 

cFlagsl. freeText 

Whether to free contents when freeing the Cell. 

cFlags 1 .alignment 

Text justification. 
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cFlagsl.bordered 
cFlagsl.bezeled 
cFlags 1 .selectable 
cFlagsl.scrollable 
cFlags 1 .entry Type 
cFlags2.continuous 

cFlags2.actOnMouseDown 

cFlags2.floatLeft 

cFlags2.floatRight 

cFlags2. autoRange 

cFlags2.actOnMouseDragged 

cFlags2.noWrap 

cFlags2.dontActOnMouseUp 


Whether the Cell has a border. 

Whether the Cell has a bezeled border. 

Whether the text is selectable. 

Whether the text is scrollable. 

Type of data accepted. 

Sends action continuously to target while control is 
active. 

Sends action on the mouse-down (rather than the 
mouse-up). 

Digits to left of decimal when text is floating-point 
number. 

Digits to right of decimal when text is floating-point 
number. 

Autorange decimal when text is floating point 
number. 

Send action every time the mouse changes position. 
0 = word wrap, 1 = character wrap. 

Don’t send the action on the mouse-up event. 


METHOD TYPES 

Copying, initializing, and freeing a Cell 

- copy 

- copyFromZone: 

- init 

- initlconCell: 

- initTextCell: 

- free 

Determining component sizes - calcCellSize: 

- calcCellSize:inRect: 

- calcDrawInfo: 

- getDrawRect: 

- getlconRect: 

- getTitleRect: 
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Setting the Cell’s type 

- sefiype: 

-type 

Setting the Cell’s state 

- incrementState 

- setState: 

- state 

Enabling and disabling the Cell 

- isEnabled 

- setEnabled: 

Modifying the Icon 

- icon 


- setlcon: 

Setting Cell values 

- double Value 

- float Value 

- int Value 

- setDoubleValue: 

- setFloatValue: 

- setlntValue: 

- setStringValue: 

- setStringValueNoCopy: 

- setStringValueNoCopy:shouldFree: 

- string Value 

Modifying text attributes 

- alignment 

- font 

- isEditable 

- isScrollable 

- isSelectable 

- setAlignment: 

- setEditable: 

- setFont: 

- setScrollable: 

- setSelectable: 

- setTextAttributes: 

- setWrap: 

Editing text 

- edit: in View: editor: delegate: event: 

- endEditing: 

- select: inView: editor delegate: start: length: 

Validating input 

- entry Type 

- isEntry Acceptable: 

- setEntryType: 

Formatting data 

- setFloatingPointFormat:left:right: 
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Modifying graphic attributes - isBezeled 

- isBordered 

- isOpaque 

- setBezeled: 

- setBordered: 

Setting parameters - getParameter: 

- setParametento: 


Interacting with other Cells 

Displaying 

Target and action 


Assigning a tag 

Handling keyboard alternatives 
Tracking the mouse 

Managing the cursor 
Archiving 


- takeDoubleValueFrom: 

- takeFloatValueFrom: 

- takelntValueFrom: 

- takeString ValueFrom: 

- controlView 

- drawInside:inView: 

- drawSelf:inView: 

- highlight:inView:lit: 

- isHighlighted 

- action 

- getPeriodicDelayiandlnterval: 

- isContinuous 

- sendActionOn: 

- set Action: 

- setContinuous: 

- setTarget: 

- target 

- setTag: 

-tag 

- keyEquivalent 

- continueTracking:at:inView: 

- mouseDownFlags 

+ prefersTrackingUntilMouseUp 

- startTrackingAt:inView: 

- stopTracking: at: in View :mouseIsUp: 

- trackMouse:inRect:ofView: 

- resetCursorRect:inView: 

- awake 

- read: 

- write: 
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CLASS METHODS 


prefersTrackingUntilMouseUp 

+ (BOOL)prefersTrackingUntHMouseUp 

Returns NO by default. Override this method to return YES if the Cell should, after a 
mouse-down event, track mouse-dragged and mouse-up events even if they occur 
outside the Cell’s frame. This method is overridden to ensure that a SliderCell in a 
matrix doesn’t stop responding to user input (and its neighbor start responding) just 
because the knob isn’t dragged in a perfectly straight line. 


INSTANCE METHODS 

action 

- (SEL)action 

Returns a null selector. This method is overridden by Action Cell and its subclasses, 
which actually implement the target object and action method. 

alignment 

- (int)alignment 

Returns the alignment of text in the Cell. The return value can be one of three 
constants: NXJLEFTALIGNED, NX_CENTERED, or NXJRIGHTALIGNED. 

awake 

- awake 

Used during unarchiving; initializes static variables for the Cell class. Returns self. 
calcCellSize: 

- calcCellSize:(NXSize *)theSize 

Returns self and, by reference, the minimum width and height required for displaying 
the Cell. It’s implemented by calling calcCellSizetinRect: with the rectangle argument 
set to a rectangle with very large width and height. This should be overridden if that is 
not the proper way to calculate the minimum width and height required for displaying 
the Cell (SliderCell overrides this method for that reason). 
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calcCellSize: inRect: 


- calcCellSize: (NXSize *)theSize inRect:(const NXRect *)aRect 

Returns self and, by reference, the minimum width and height required for displaying 
the Cell in a given rectangle. If it’s not possible to fit, the width and/or height could be 
bigger than the ones of the rectangle. The computation is done by trying to size the Cell 
so that it fits in the rectangle argument (by wrapping the text for instance). If a choice 
must be made between extending the width or height of aRect to fit the text, the height 
will be extended. 

calcDrawInfo: 

- calcDrawInfo: (const NXRect *)aRect 

Objects using Cells generally maintain a flag that informs them if any of their Cells has 
been modified in such a way that the location or size of the Cell should be recomputed. 
If so a method (usually named calcSize) is automatically invoked before displaying the 
Cell; this method invokes Cell’s calcDrawInfo: for each Cell. Subclasses of Cell can 
override calcDrawInfo: to cache some information that could speed up the drawing of 
the Cell. In Cell, this method does nothing and returns self. 

See also: - calcSize (Matrix) 

continueT racking: at: in V iew: 

- (BOOL)continueTracking: (const NXPoint *)lastPoint 

at:(const NXPoint *)currentPoint 
in View icontrolView 

Returns YES if it’s OK to keep tracking. This method is invoked by 
trackMouse:inRect:ofView: as the mouse is dragged around inside the Cell. By 
default, this method returns YES when the cFlags2.continuous or 
cFlags2.actOnMouseDragged is set to YES. This method is often overridden to 
provide more sophisticated tracking behavior. 

control View 

- controlView 

Returns nil. This method is implemented abstractly, since Cell doesn’t have an instance 
variable for the view in which an instance is drawn. It’s overridden by ActionCell and 
its subclasses, which use the controlView’s id as the only argument in the action 
message when it’s sent to the target. 

See also: - controlView (ActionCell) 
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copy 


- copy 

Allocates and returns a copy of the receiving Cell. The copy is allocated from the 
default zone and is assigned the contents of the receiver. 

copyFromZone: 

- copyFromZone :(NXZone *)zone 

Allocates and returns a copy of the receiving Cell. The copy is allocated from zone and 
is assigned the contents of the receiver. When you subclass Cell, override this method 
to send the message [super copyFromZone:], then copy each of the subclass’s unique 
instance variables separately. 

double Value 

- (double)double Value 

Returns the receiver’s double value by converting its contents to a double using the C 
function atof(). Returns 0 if the cell type is not NX_TEXTCELL. 

drawlnside: in View: 

- drawlnside: (const NXRect *)cellFrame in View icontrolView 

Draws the inside of the Cell; it’s the same as drawSelf:inView: except that it does not 
draw the bezel or border if there is one. All subclasses of Cell which implement 
drawSelf:inView: must implement drawInside:inView:. drawInside:inView: 
should never invoke drawSelf:inView:, but drawSelf:inView: can invoke 
drawInside:inView: (in fact, it often does), drawlnside: in View: is invoked from the 
Control class’s drawCelllnside: method and is used to cause minimal drawing to be 
done in order to update the value displayed by the Cell when the contents is changed. 
This becomes more important in more complex Cells such as ButtonCell and 
SliderCell. The passed cellFrame should be the frame of the Cell (i.e., the same 
cellFrame passed to drawSelf:inView:), not the rectangle returned by getDrawRect:! 
Be sure to lock focus on the controlView before invoking this method. If 
cFlagsl.highlighted is YES, then the Cell is highlighted (by changing light gray to 
white and white to light gray throughout cellFrame ). Returns self. 
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drawSelf:inView: 


- drawSelf: (const NXRect *)cellFrame inView '.controlView 

Displays the contents of a Cell in a given rectangle of a given view. Lock the focus on 
the controlView before invoking this method. It draws the border or bezel (if any), then 
invokes drawlnside:inView:. A text Cell displays its text in the rectangle by using a 
global Text object, an icon Cell displays its icon centered in the rectangle if it fits in the 
rectangle, by setting the icon origin on the rectangle origin if it does not fit. Nothing is 
displayed for NX_NULLCELL. You can override this method if you want a display 
that is specific to your own subclass of Cell. Returns self. 

See also: - drawlnside:inView: 

edit: in V iew: editor: delegate: event: 

- edit:(const NXRect *)aRect 

inView '.controlView 
editor: textObj 
delegate lanObject 
event :(NXEvent *)theEvent 

Use this method to edit the text of a Cell by using the Text object textObj in response 
to an NX_MOUSEDOWN event. The aRect argument must be the one you have used 
when displaying the Cell, the Event is the NX_MOUSEDOWN event. anObject is 
made the delegate of the Text object textObj used for the editing: it will receive the 
methods such as textDidEnd'.endChar:, textWillEnd, textDidResize, 
textWillResize, and others sent by the Text object while editing. If the cell type is not 
equal to NX_TEXTCELL no editing is performed, otherwise the Text object is sized to 
aRect and its superview is set to controlView, so that it exactly covers the Cell. Then 
it’s activated and editing begins. It’s the responsibility of the delegate to end the 
editing, remove any data from the textObj and invoke endEditing: on the Cell in the 
textDidEnd:endChar: method. Returns self. 


endEditing: 

- endEditing: textObj 


Use this method to end the editing you began with edit: in View: editor: delegate: event: 
or select:inView:editor:delegate:start:length:. Usually this method is called by the 
textDidEnd:endChar: method of the object you are using as the delegate for the Text 
object (most often a Matrix or TextField). It removes the Text object from the view 
hierarchy and sets its delegate to nil. Returns self. 


entryType 

- (int)entryType 

Returns the type of data allowed in the Cell. See setEntryType: for the list of valid 
types. 
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float Value 

- (float)float Value 


Returns the receiver’s float value by converting its contents to a float using the C 
function atof(). Returns 0.0 if the cell type is not NX_TEXTCELL. 


font 
- font 

Returns the font used to display text in the Cell. Returns nil if the Cell is not of type 
NX_TEXTCELL. 


free 
- free 

Frees all disposable storage used by the Cell. If cFlagsl.freeText is YES, then the 
contents instance variable is freed. Returns nil. 


getDrawRect: 

- getDrawRect: (NXRect *)theRect 


Returns self and, by reference, the rectangle into which the Cell will draw its “insides.” 
In other words, this method usually returns the rectangle which is touched by 
draw!nside:inView:. Pass the bounds of the Cell in theRect. 


getlconRect: 

- get!conRect:(NXRect *)theRect 


Returns self and, by reference, the rectangle into which the icon will be drawn. Pass 
the bounds of the Cell in theRect. If this Cell does not draw an icon, theRect is 
untouched. 


getParameter: 

- (int)getParameter:(int)aPararaeter 

Returns the most usual flags of a Cell. The following constants corresponds to the 
different flags: 

NX_CELLDISABLED 

NX.CELLSTATE 

NX_CELLHIGHLIGHTED 

NX_CELLEDITABLE 


It is, in general, much better to invoke the “is” methods (isEnabled, isHighlighted, 
isEditable) rather than use getParameter:. 
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getPer iodicDelay: andlnter val: 

- getPeriodicDelay:(float*)de/dry andInterval:(float*)mtemz/ 

Sets two values: the amount of time (in seconds) that a continuous button will pause 
before starting to periodically send action messages to the target object, and the interval 
(also in seconds) at which those messages are sent. Periodic messaging behavior is 
controlled by Cell’s sendActionOn: and setContinuous: methods. (By default, Cell 
sends the action message on mouse up events.) The default values returned by this 
method are 0.2 seconds delay and 0.025 seconds interval. Can be overridden. Returns 
self. 

getTitleRect: 

- getTitleRect: (NXRect *)theRect 

Returns self and, by reference, the rectangle into which the text will be drawn. Pass the 
bounds of the Cell in theRect. If this Cell does not draw any text, theRect is untouched. 


highlight:inView:lit: 

- highlight: (const NXRect *)cellFrame 

in View icontrolView 
lit: (BOOL )flag 

If cFlagsl.highlighted is not equal to flag, it’s set to flag and the rectangle cellFrame 
is highlighted in controlView. (You must lockFocus on controlView before calling this 
method.) The default is simply to composite with NX_HIGHLIGHT inside the bounds 
of the cellFrame. Override this method if you want a more sophisticated highlighting 
behavior in a Cell subclass. Note that the highlighting that the base Cell class does will 
not appear when printed (although subclasses like TextFieldCell, SelectionCell, and 
ButtonCell can print themselves highlighted). This is due to the fact that the base Cell 
class is transparent, and there is no concept of transparency in printed output. Returns 
self. 

icon 

- (const char *)icon 

Returns the name of the icon currently used by the Cell. Returns NULL if the cell type 
is not NX_ICONCELL. 
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incrementState 
- incrementState 

Adds 1 to the state of the Cell, wrapping around to 0 from maximum value (for the base 
Cell class, 1 wraps to 0). Subclasses may want to change the meaning of this method 
(for multistate Cells, for example). Remember that if you want the visual appearance 
of the Cell to reflect a change in state, you must invoke drawSelfiinView: after altering 
the state (and your drawSelf:inView: must draw the different states in different 
ways—the default implementation of the Cell class does not visually distinguish 
differences in state). Returns self. 


init 


- init 


Initializes and returns the receiver, a new Cell instance, as type NX_NULLCELL. This 
method is the designated initializer for null cells. 

initlconCell: 

- initlconCell: (const char *)iconName 

Initializes and returns the receiver, a new Cell instance, as type NX_ICONCELL. The 
icon is set to iconName. This method is the designated initializer for icon Cells. 

See also: - findlmageFor: (NXImage), - name (NXImage) 
initTextCell: 

- initTextCell:(const char *)aString 

Initializes and returns the receiver, a new Cell instance, as type NX__TEXTCELL. The 
string value is set to aString. This method is the designated initializer for text Cells. 

intValue 

- (int)intValue 

Returns the Cell’s integer value by converting its contents to an integer using the C 
function atoi(). Returns 0 if the cell type is not NX_TEXTCELL. 

isBezeled 

- (BOOL)isBezeled 

Returns YES if the Cell has a bezeled border, NO otherwise. 
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isBordered 

- (BOOL)isBordered 


Returns YES if the Cell is surrounded by a 1-pixel black frame, NO otherwise. The 
default is NO. 


isContinuous 

- (BOOL)isContinuous 

Returns YES if the Cell continuously sends its action message to the target object when 
tracking. This usually has meaning only for subclasses of Cell that implement target 
and action instance variables (ActionCell and its subclasses), although some Control 
subclasses will send a default action to a default target even if the Cell does not itself 
have a target and action. 


isEditable 

- (BOOL)isEditable 

Returns YES if the text in the Cell is editable, NO otherwise. The default is NO. 


isEnabled 

- (BOOL)isEnabled 

Returns YES if the Cell is enabled, NO otherwise. The default is YES. 


isEntry Acceptable: 

- (BOOL)isEntryAcceptable: (const char *)aString 

Tests whether aString matches the Cell’s entry type, set by the setEntryType: method. 
Returns YES if it aString is acceptable by the receiving Cell, NO otherwise. This 
method is invoked by Form, Matrix, and other Controls to see if a new text string is 
acceptable for this Cell. This method doesn’t check for overflow. It can be overridden 
to enforce specific restrictions on what the user can type into the Cell. If aString is 
NULL or empty, this method returns YES. 

See also: - setEntryType: 

isHighlighted 

- (BOOL)isHighlighted 

Returns YES if the Cell is currently highlighted, NO otherwise. The Cell can be 
highlighted by calling highlight:inView:lit:. 
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isOpaque 

- (BOOL)isOpaque 

Returns YES if the Cell is opaque (i.e., it touches every pixel in its bounds), NO 
otherwise. The base Cell class is opaque if and only if it has a bezel. Subclasses which 
draw differently should override this appropriately. 

isScrollable 

- (BOOL)isScroIlable 

Returns YES if typing past the end of the text in the Cell will cause the Cell to scroll to 
follow the typing. The default return value is NO. 

isSelectable 

- (BOOL)isSelectable 

Returns YES if the text in the Cell is selectable, NO otherwise. The default return value 
is NO. 

keyEquivalent 

- (unsigned short)keyEquiva!ent 

Returns 0. Should be overridden by subclasses to return a key equivalent for the 
receiver. 

mouseDownFlags 

- (int)mouseDownFlags 

Returns the flags (e.g., NX_SHIFTMASK) that were set when the mouse went down to 
start the current tracking session. This is useful if you want to use these flags, but don’t 
want the overhead of having to add NX_MOUSEDOWNMASK to the sendActionOn: 
mask just to get those flags. This method is only valid during tracking and does not 
work if the target of the Cell initiates another Cell tracking loop as part of its action 
method (for example, like PopUpLists do). 


read: 


- read:(NXTypedStream *)stream 
Reads the Cell from the typed stream stream. 
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resetCursorRect:inView: 


- resetCursorRect: (const NXRect *)cellFrame mWtw'.controlView 

If the type of the Cell is NX_TEXTCELL, then a cursor rectangle is added to 
controlView (via addCursorRect:cursor:). 

See also: - addCursorRect:cursor: (View, Control) 

select:inView:editor:delegate:start:length: 

- select:(const NXRect *)aRect 

in View -.controlView 
editor itextObj 
delegsAeianObject 
stSLrt:(int)selStart 
iength:(int)selLength 

Similar to edit:inView:editor:delegate:event: but you can invoke it in any situation, 
not only on a mouse-down event. You must specify the beginning and the length of the 
selection. 

sendActionOn: 

- (int)sendActionOn:(int)ra< 2 s& 

Resets flags to determine when the action is sent to the target while tracking. Can be 
any combination of: 

NX_MOUSEUPMASK 
NX_MOU SEDOWNM ASK 
NX_MOUSEDRAGGEDM ASK 
NX_PERIODICMASK 

The default is NX_MOUSEUPMASK. You can use the setContinuous: method to 
turn on the bit in the NX_PERIODICMASK or the NX_MOUSEDRAGGEDMASK 
(whichever is appropriate to the given subclass of Cell) in the current mask. 

Returns the old mask. 

set Action: 

- setAct\on:(SEL)aSelector 

Does nothing. Should be overridden by subclasses that implement target and action 
instance variables (ActionCell and its subclasses). Returns self. 
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setAlignment: 

- setAlignment :(int )mode 


Sets the alignment of text in the Cell and returns self, mode should be one of three 
constants: NX_LEFTALIGNED, NX_CENTERED, or NX_RIGHTALIGNED. 


setBezeled: 

- setBezeled:(BOOL)/fog 


If flag is YES, then the Cell is surrounded by a bezel, otherwise it’s not. setBordered: 
and setBezeled: are mutually exclusive options. Returns self. 


setBordered: 

- setBordered \{BOOL)flag 

If flag is YES, then the Cell is surrounded by a 1-pixel black frame, otherwise it’s not. 
setBordered: and setBezeled: are mutually exclusive options. Returns self. 


setContinuous: 

- setContinuous:(BOOL)/?<zg 

Sets whether a Cell continuously sends its action message to the target object when 
tracking. Normally, this method will simply add NX_PERIODICMASK or 
NX_MOUSEDRAGGEDMASK to the mask set with sendActionOn:, depending on 
which setting is appropriate to the subclass implementing it. In the base Cell class, this 
method adds NX_PERIODICMASK to the mask. These settings usually have meaning 
only for ActionCell and its subclasses which implement instance variables for the target 
object and action method. However, some Control subclasses will send a default action 
to a default target when the Cell itself doesn’t define target and action instance 
variables. 

See also: - sendActionOn: 


setDoubleValue: 

- setDoubleValue: (double)aDouble 


Sets the receiver to represent aDouble, by replacing the contents with the character 
string representing aDouble. Does nothing if the cell type is not NX_TEXTCELL. 
Returns self. 
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setEditable: 

- setEditable :(BOOL)flag 

Sets the editable state of the Cell. If flag is YES, then the text is also set to be selectable. 
If flag is NO, then the text is set not selectable. Returns self. 

See also: - edit:inView:editor:delegate:event: 

setEnabled: 

- setEnabled: (BOOL)flag 

Sets the enabled state of the Cell. Returns self. 


setEntryType: 

- setEntryType:(int)a7ype 

This method sets the type of data allowed in the Cell. aType is one of these four 
constants: 

NX_ANYTYPE 

NX_(POS)INTTYPE 

NX_(POS)FLOATTYPE 

NX_(POS)DOUBLETYPE 

If the Cell is not of type NX_TEXTCELL, it’s automatically converted, in which case 
its support instance variable is set to the default font (Helvetica 12.0), and its string 
value is set to “Cell” (the default). 

The entry type is checked by the isEntryAcceptable: method. That method is used by 
Controls that contain editable text (such as Matrix and TextField) to validate that what 
the user has typed is correct. If you want to have a custom Cell accept some specific 
type of data (other than those listed above), you can override the isEntry Acceptable: 
method to check for the validity of the data the user has entered. 

See also: - isEntryAcceptable:, - setFloatingPointFormat:left:right: 
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setFloatingPointFormat:left:right: 

- setFloatingPointFormat: (BOOL)autoRange 

, left: (unsigned )leftDigits 

right ‘.(unsigned )rightDigits 

Sets whether floating-point numbers are autoranged, and sets the size of the fields to the 
left and right of the decimal point. leftDigits must be between 0 and 10. rightDigits 
must be between 0 and 14. If leftDigits is 0, then the number is not formatted. If 
rightDigits is 0, then the fractional part of the floating-point number is truncated (i.e., 
the floating-point number is printed as if it were an integer). Otherwise, leftDigits 
specifies the number of digits to the left of the decimal point, and rightDigits specifies 
the number of digits to the right. If autoRange is YES, the number will be fit into a field 
that’s leftDigits + rightDigits + 1 spaces wide and the decimal point will be autoranged 
to fit that field (the field will also be padded with zeros). To turn off formatting, simply 
invoke this routine with leftDigits - 0. If the entryType of the Cell is not already 
NX_FLOATTYPE, NX_POSFLOATTYPE, NX_DOUBLETYPE, or 
NXJPOSDOUBLETYPE, it’s set to NX_FLOATTYPE. Returns self. 

setFloatValue: 

- setFloatValue ‘.(floafiaFloat 

Sets cell-specific float value, by replacing its contents by the character string 
representing the float. Does nothing if the cell type is not NX_TEXTCELL. Returns 
self. 

setFont: 

- setFont ifontObj 

Sets the font to be used when displaying text in the Cell. Does nothing if the Cell is not 
of type NX_TEXTCELL. Returns self. 

setlcon: 

- setlcon: (const char *)iconName 

Invoke this method to set the icon of the Cell to the icon represented by iconName (an 
icon is a named NXImage—see the NXImage class). If the Cell was not an 
NX_ICONCELL, it’s automatically converted. Sets the support instance variable to 
iconName, and sets the contents instance variable to the result of sending the name 
message to that NXImage. If you specify an invalid NXImage name, you will get a 
default icon (you can verify that the NXImage you requested was valid by checking the 
result of sending the icon message to the Cell to be sure it matches the iconName you 
supplied). Returns self. 

See also: - findlmageNamed (NXImage), - name (NXImage) 
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setlnt Value: 


- setIntValue:(int)<z«/«t 

Sets cell-specific integer value by replacing its contents by the character string 
representing anlnt. Does nothing if the cell type is not NX_TEXTCELL. Returns self. 

setParameter:to: 

- setParameter:(int)aAzrameter to:(int)va/wc 

Sets the most usual flags of a Cell. Calling this method could result in unpredictable 
results in subclasses. It’s much safer to invoke the appropriate set... method to set a 
specific flag. Returns self. 

See also: - getParameter:, - highlightlnViewilit:, - setEditable:, - setEnabled:, 

- setState: 

setScrollable: 

- setScrollable: (BOOL )flag 

Sets whether, while editing, the Cell will scroll to follow typing. Returns self. 

See also: - edit:inView:editor:delegate:event: 

setSelectable: 

- setSelectable: (BOOL )flag 

If flag is YES, then the text is selectable but not editable. If NO, then the text is static 
(not editable or selectable). Returns self. 

See also: - edit:inView:editor:delegate:event: 
setState: 

- setState :(int)value 

Sets the state of the Cell to 0 if value is 0, to 1 otherwise. Returns self. 

See also: - incrementState 


Application Kit Classes: Cell 2-159 



setString Value: 

- setString Value: (const char *)aString 

Invoke this method to set the contents instance variable to a copy of aString. If the Cell 
was not of type NX_TEXTCELL, it’s automatically converted, in which case its 
support instance variable is set to the default font (Helvetica 12.0). If floating point 
parameters have been set (via setFIoatingPointParameters:Ieft:right:) and the type 
of the Cell is NX_(POS){FLOAT,DOUBLE}TYPE, then the string will be tested for 
being a float or a double. If it’s a float or a double, then the appropriate 
parameterization will be applied; otherwise, the string will be copied directly. Returns 
self. 

setString ValueNoCopy: 

- setStringValueNoCopy:(const char *)aString 

Similar to setString Value: but does not make a copy of aString. The Cell records that 
it does not have to dispose of its contents instance variable when it receives the free 
message. Note that if you set a string this way, then the floating-point parameters will 
not be applied (since no copy of the string is being made). Returns self. 

setStringValueNoCopy:shouIdFree: 

- setStringValueNoCopy:(char *)aString shouldFree:(B OOL)flag 

Similar to setString ValueNoCopy:, but the caller can specify if the contents instance 
variable will be freed when the Cell receives the free message. Note that if you set a 
string this way, then the floating-point parameters will not be applied (since no copy of 
the string is being made). If aString == contents, then if flag is NO, cFlagsl.freeText 
will be set to NO. Returns self. 

setTag: 

- setTag :{ini)anlnt 

Does nothing. This method is overridden by ActionCell and its subclasses to support 
multiple-Cell controls (Matrix and Form). Returns self. 

setTarget: 

- sttJ&rgetianObject 

Does nothing. This method is overridden by ActionCell and its subclasses that 
implement the target object and action method. Returns self. 
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setT ext Attr ib utes: 

- setText Attributes : textObj 

Invoked just before any drawing or editing occurs in the Cell. It’s intended to be 
overridden. If you do override this method you must invoke 
[super setTextAttributes:textO£>/] first. If you do not, you risk inheriting drawing 
attributes from the last Cell which drew any text. You should invoke only the following 
two Text instance methods: 

setBackgroundGray: 
setTextGray: 

Do not set any other parameters in the Text object. 

You should return textObj as the return value of this method. Therefore, if you want to 
substitute some other Text object to draw with (but not edit, editing always uses the 
window’s field editor), you can return that object instead of textObj and it will be used 
for the draw that caused setText Attributes: to be called. 

TextFieldCell, a subclass of ActionCell, allows you to set the grays without creating 
your own subclass of Cell. You only need to subclass Cell to control the gray values if 
you don’t want all of the functionality (and instance variable usage) of an ActionCell. 

Defaults: If the Cell is disabled, its text gray will be NX_DKGRAY, otherwise it will 
be NX_BLACK. If the Cell has a bezel, then its background gray will be NX_WHITE, 
otherwise it will be NX_LTGRAY. The Text object does not paint the background gray 
before drawing; it only uses the background gray to erase characters while editing. The 
Cell class does paint the NX_WHITE background when it draws a bezeled Cell, but 
does not paint any background (i.e., it’s transparent) otherwise. 

Note that most of the other text object attributes can be set via Cell methods (setFont:, 
setAlignment:, setWrap:) so you need only override this method if you need to set the 
gray values. Returns self. 

setType: 

- setType :(int)aType 

Sets the type of the Cell. It should be NX_TEXTCELL, NXJCONCELL, or 
NX_NULLCELL. If aType is NX_TEXTCELL and the current type is not 
NX_TEXTCELL, then the font is set to the default font (Helvetica 12.0), and the string 
value of the Cell is set to the default string, “Cell”. If aType is NXJCONCELL and 
the current type is not NXJCONCELL, then the icon for the Cell is set to be the default 
icon, “square 16”. 
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setWrap: 

- setWrap:(BOOL)yfog 

If flag is YES, then the text (when displaying, not editing) will be wrapped to word 
breaks. Otherwise, it will not. The default is YES. 

startTrackingAtrinView: 

- (BOOL)startlYackingAt: (const NXPoint *)startPoint in Vie w : controlView 

This method returns YES if and only if the Cell is continuous, that is, if 
cFlags2.continuous or cFlags2.actOnMouseDragged is YES. Called via 
trackMouse:inRect:ofView: the first time the mouse appears in the Cell needing to be 
tracked. Default is to do nothing. Should return YES if it’s OK to track based on this 
starting point, otherwise it returns NO. This method is often overridden to provide 
more sophisticated tracking behavior. 

state 

- (int)state 

Returns the state of the Cell (0 or 1). The default is 0. 

stopTracking:at:inView:mouseIsUp: 

- stopTracking: (const NXPoint *)lastPoint 

at:(const NXPoint *)stopPoint 
iriViewicontrolView 
mouselsUp: (BOOL)flag 

Invoked via trackMouse:inRect:ofView: when the mouse has left the bounds of the 
Cell, or the mouse button has gone up. flag is YES if the mouse button went up to cause 
this method to be invoked. The default method does nothing and returns self. This 
method is often overridden to provide more sophisticated tracking behavior. Returns 
self. 

string Value 

- (const char *)string Value 

Returns a pointer to the contents instance variable. 


tag 

- (int)tag 

Returns -1. Overridden by subclasses such as ActionCell to provide a way to identify 
Cells in a multiple-Cell Control such as Matrix or Form. 
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takeDoubleV alueFrom: 

- takeDoubleValueFronusettder 

Sets the receiving Cell’s double-precision floating point value to the value returned by 
sender' s double Value method. Returns self. 

This method can be used in action messages between Cells. It permits one Cell 
(sender) to affect the value of another Cell (the receiver). For example, a TextFieldCell 
can be made the target of a SliderCell, which will send it takeDoubleValueFrom: 
action message. The TextFieldCell will get the SliderCell’s double value, turn it into 
a text string, and display it. 

See also: - takeDoubleValueFrom: (Control), - setDoubleValue:, - double Value 

takeFloat V alueFrom: 

- takeFloatValueF rom: sender 

Sets the receiving Cell’s single-precision floating-point value to the value returned by 
sender's floatValue method. Returns self. 

This is the same as takeDoubleValueFrom: except it works with floats rather than 
doubles. 

See also: - takeFloatValueFrom: (Control), - setFloatValue:, - floatValue 

takelnt V alueFrom: 

- takelntValueFrom : sender 

Sets the receiving Cell’s integer value to the value returned by sender's intValue 
method. Returns self. 

This is the same as takeDoubleValueFrom: except it works with ints rather than 

doubles. 

See also: - takelntValueFrom: (Control), - setlntValue:, - intValue 


takeStr ing ValueFrom: 

- takeStringValueFrom: sender 

Sets the receiving Cell’s string value to the value returned by sender's stringValue 
method. Returns self. 

This is the same as takeDoubleValueFrom: except it works with strings rather than 
doubles. 

See also: - takeStringValueFrom: (Control), - stringValue, - setStringValue: 
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target 

- target 

Returns nil. This method is overridden by ActionCell and its subclasses that implement 
target and action instance variables. Returns self. 

trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent *)theEvent 

inRect:(const NXRect *)cellFrame 
ofView icontrolView 

This method is called by Controls to implement the tracking behavior of a Cell. It’s 
generally not overridden since the default implementation provides a simple interface 
to some other, simpler, tracking routines: 

(BOOL)startTrackingAt:(NXPoint *)startPoint 
inViewxontrolView 

(BOOL)continueTracking:(NXPoint *)lastPoint 
at:(NXPoint *)currentPoint 
inViewxontrolView 
stopTracking:(NXPoint *)lastPoint 
at:(NXPoint *)endPoint 
in View icontrolView 
mouseIsUp:(B OOL)flag 

This method invokes startTrackingAt:inView: first, then, as mouse-dragged events 
are intercepted, continueTracking:at:inView: is called, and, finally, when the mouse 
leaves the bounds (if cellFrame is NULL, then the bounds are considered infinitely 
large), or if the mouse button goes up, stopTracking:at:inView:mouseIsUp: is called. 
If this interface is insufficient for the needs of your Cell, you may override 
trackMouse:inRect:ofView: directly. It’s this method’s responsibility to invoke the 
control View’s send Action :to: method when appropriate (before, during, or after 
tracking) and to return YES if and only if the mouse goes up within the Cell during 
tracking. If the Cell’s action is sent on mouse down, then startTrackingAt:inView: is 
called before the action is sent and the mouse is tracked until it goes up or out of 
bounds. If the Cell sends its action periodically, then the action is sent periodically to 
the target even if the mouse is not moving (although continueTracking:at:inView: is 
only called when the mouse changes position). If the Cell’s action is sent on mouse 
dragged, then continueTracking:at:inView: is called before the action is sent. The 
state of the Cell is incremented (via incrementState) before the action is sent and after 
stopTracking:at:inView: is called when the mouse goes up. Returns self. 

type 

- (int)type 

Returns the type of the Cell. Can be one of NX_NULLCELL, NXJCONCELL or 
NX_TEXTCELL. 
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write: 

- write :(NXTypedStream *)stream 

Writes the Cell to the typed stream stream. Returns self. 

CONSTANTS AND DEFINED TYPES 

/* Cell Data Types */ 

#define NX_ANYTYPE 0 

#define NX_INTTYPE 1 

#define NX_POSINTTYPE 2 

#define NX_FLOATTYPE 3 

#define NX_POSFLOATTYPE 4 

#define NX_DATETYPE 5 

#define NX_DOUBLETYPE 6 

#define NX_POSDOUBLETYPE 7 

/* Cell Types */ 

#define NX_NULLCELL 0 

tdefine NX_TEXTCELL 1 

#define NX_ICONCELL 2 

/* Cell & ButtonCell */ 

#define NX_CELLDISABLED 0 

#define NX_CELLSTATE 1 

#define NX_CELLEDITABLE 3 

#define NX_CELLHIGHLIGHTED 5 

#define NX_LIGHTBYCONTENTS 6 

#define NX_LIGHTBYGRAY 7 

#define NX_LIGHTBYBACKGROUND 9 

#define NX_ICONISKEYEQUIVALENT 10 
# define NX__HAS ALP HA 11 

tdefine NX_BORDERED 12 

tdefine NXJDVERLAPPINGICON 13 

tdefine NX_ICONHORIZONTAL 14 

tdefine NX_ICONONLEFTORBOTTOM 15 
tdefine NX_CHANGECONTENTS 16 

/* ButtonCell icon positions */ 
tdefine NX_TITLEONLY 0 

tdefine NX_ICONONLY 1 

tdefine NX_ICONLEFT 2 

tdefine NX_ICONRIGHT 3 

tdefine NX_ICONBELOW 4 

tdefine NX_ICONABOVE 5 

tdefine NX ICONOVERLAPS 6 


Application Kit Classes: Cell 2-165 



/* ButtonCell highlightsBy and showsStateBy mask */ 


#define NX_NONE 0 
#define NX_CONTENTS 1 
#define NX_PUSHIN 2 
#define NX_CHANGEGRAY 4 
#define NX CHANGEBACKGROUND 8 


/* Cell whenActionlsSent mask flag */ 

#define NX PERIODICMASK (1 « (NX LASTEVENT+1)) 
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Clip View 


INHERITS FROM View : Responder : Object 

DECLARED IN appkit/ClipView.h 

CLASS DESCRIPTION 

The Clip View class provides basic scrolling behavior by displaying a portion of a 
document that may be larger than the Clip View’s frame rectangle. It also provides 
clipping to ensure that its document is not drawn outside the Clip View’s frame. The 
Clip View has one subview, the document view , which is the view to be scrolled. Since 
a subview’s coordinate system is positioned relative to its superview’s origin, the 
Clip View changes the displayed portion of the document by translating the origin of its 
own bounds rectangle. 

When the Clip View is instructed to scroll its document view, it copies as much of the 
previously visible document as possible, unless it received a setCopyOnScroll:NO 
message. The Clip View then sends its document view a message to either display or 
mark as invalidated the newly exposed region(s) of the ClipView. By default it will 
invoke the document view’s display:: method, but if the ClipView received a 
setDisplayOnScroll:NO message, it will invoke the document view’s invalidate:: 
method. 

The ClipView sends its superview (usually a ScrollView) a reflectScroll: message to 
notify it whenever the relationship between the ClipView and the document view has 
changed. This allows the superview to update any controls it manages to reflect the 
change. You don’t normally use the ClipView class directly; it is used by ScrollView 
which provides standard controls to allow the user to perform scrolling. However, you 
might use the ClipView class to implement a class similar to ScrollView. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Declared in ClipView 

float 

backgroundGray; 


id 

doc View; 


id 

cursor; 
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backgroundGray 

The gray value used to fill the area of the 

Clip View not covered by the opaque portions of 
the document view. 

doc View 

The Clip View’s document view. 

cursor 

The cursor that’s used inside the Clip View’s 
frame rectangle. 

METHOD TYPES 


Initializing the class object 

+ initialize 

Initializing and freeing a Clip View 

- initFrame: 

- free 

Modifying the frame rectangle 

- moveTo:: 

- rotateTo: 

- sizeTo:: 

Modifying the coordinate system 

- rotate: 

- scale:: 

- setDrawOrigin:: 

- setDrawRotation: 

- setDrawSize:: 

- translate:: 

Managing component Views 

- doc View 

- setDocView: 

- getDocRect: 

- getDocVisibleRect: 

- resetCursorRects 

- setDocCursor: 

Modifying graphic attributes and displaying 

- backgroundGray 

- setBackgroundGray: 

- backgroundColor 

- setBackgroundColor: 

- drawSelf:: 

Scrolling 

- autoscroll: 

- constrainScroll: 

- rawScroll: 

- setCopyOnScroll: 

- setDisplayOnScroll: 

Coordinating with other Views 

- descendantFlipped: 

- descendantFrameChanged: 
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Archiving 


- awake 

- read: 

- write: 


CLASS METHODS 


initialize 
+ initialize 

Sets the current version of the Clip View class. You never send an initialize message; 
it’s sent for you when the application starts. Returns self. 


INSTANCE METHODS 

autoscroll: 

- autoscroll :(NXEvent *)theEvent 

Performs automatic scrolling of the document. This message is sent to the document 
view when the mouse is dragged from a position within the Clip View to a position 
outside it. The document view then sends this message to its Clip View. You never send 
an autoscroll: message directly to a Clip View. Returns nil if no scrolling occurs; 
otherwise returns self. 

See also: - autoscroll: (View) 

awake 

- awake 

Overrides View’s awake method to ensure additional initialization. After a Clip View 
has been read from an archive file, it will receive this message. You should not invoke 
this method directly. Returns self. 

backgroundColor 

- (NXColor)backgroundColor 

Returns the color of the Clip View’s background. If the background gray value has been 
set but no color has been set, the color equivalent of the background gray value is 
returned. If neither value has been set, the background color of the ClipView’s window 
is returned. 

See also: - backgroundGray, - setBackgroundColor:, - setBackgroundGray:, 

- backgroundColor (Window), NXConvertGrayToColorQ 
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backgroundGray 

- (float)backgroundGray 

Returns the gray value of the Clip View’s background. If no value has been set, the gray 
value of the Clip View’s window is returned. 

See also: - background Color, - setBackgroundGray:, 

- backgroundGray (Window) 

constrainScroll: 

- constrainScroll :(NXPoint *)newOrigin 

Ensures that the document view is not scrolled to an undesirable position. This method 
is invoked by the private method that all scrolling messages go through before it 
invokes rawScroll: or scrollClip:to:. The default implementation keeps as much of 
the document view visible as possible. You may want to override this method to 
provide alternate constraining behavior. newOrigin is the desired new origin of the 
Clip View’s bounds rectangle and is given in Clip View coordinates. Returns self. 

See also: - rawScroll: 

descendantFlipped: 

- descendantFlipped ’.sender 

Notifies the Clip View that the orientation of the coordinate system of its document view 
has changed (from unflipped to flipped, or vice versa). The orientation of the Clip View 
is changed to match the orientation of its document view. You should not invoke this 
method directly, or override it. Returns self. 

See also: - notifyWhenFlipped: (View), - setDocView: 

descendantFrameChanged: 

- descendantFrameChanged:sewfer 

Notifies the Clip View that its document view has been resized or moved. The Clip View 
may then scroll and/or display the document view, and the Clipview may also notify its 
superview to reflect the changes in the scroll position. You should not invoke this 
method directly, or override it. Returns self. 

See also: - moveTo:: (View), - sizeTo:: (View), - reflectScroll: (ScrollView), 

- notifyAncestorWhenFrameChanged: (View), - setDocView: 
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doc View 

- docView 

Returns the Clip View’s document view. 

See also: - setDocView: 

drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

Overrides View’s drawSelf:: method to fill the portions of the Clip View that are not 
covered by opaque portions of the document view. If a color value has been set and the 
ClipView is drawing itself on a color screen, the Clip View draws its background with 
the color value, otherwise it draws its background using its background gray value. 
Returns self. 

See also: - backgroundColor:, - backgroundGray:, - drawSelf:: (View) 

free 

- free 

Deallocates the memory used by the receiving ClipView. The ClipView is removed 
from the view hierarchy, and all its subviews are also freed. 

getDocRect: 

- getDocRect: (NXRect *)aRect 

Places the ClipView’s document rectangle into the structure specified by aRect. The 
origin of this rectangle is equal to the origin of the document view’s frame rectangle. 
The document rectangle’s height and width are set to the maximum corresponding 
values from the document view’s frame size and the content view’s bounds size. The 
document rectangle is used in conjunction with the ClipView’s bounds rectangle to 
determine values for any indicators of relative position and size between the ClipView 
and the document view. The ScrollView uses these rectangles to set the size and 
position of the Scrollers’ knobs. Returns self. 

See also: - reflectScroll: (ScrollView) 
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getDocVisibleRect: 

- getDocVisibleRect: (NXRect *)aRect 

Gets the portion of the document view that’s visible within the Clip View. The 
ClipView’s bounds rectangle, transformed into the document view’s coordinates, is 
placed in the structure specified by aRect. This rectangle represents the portion of the 
document view’s coordinate space that’s visible through the Clip View. However, this 
rectangle doesn’t reflect the effects of any clipping that may occur above the Clip View 
itself. Thus, if the Clip View is itself clipped by one of its superviews, this method 
returns a different rectangle than the one returned by the getVisibleRect: method, 
because the latter reflects the effects of all clipping by superviews. Returns self. 

See also: - getVisibleRect: (View) 
initFrame: 

- initFrame :(const NXRect *)frameRect 

Initializes the Clip View, which must be a newly allocated Clip View instance. The 
ClipView’s frame rectangle is made equivalent to that pointed to by frameRect. This 
method is the designated initializer for the Clip View class, and can be used to initialize 
a Clip View allocated from your own zone. By default, clipping is enabled, and the 
Clip View is set to opaque. A Clip View is initialized without a document view. Returns 
self. 

See also: - setDocView:, - initFrame: (View), + alloc (Object), 

+ allocFromZone: (Object) 

moveTo:: 

- moveTo :(NXCoord)* :(NXCoord)y 

Moves the origin of the ClipView’s frame rectangle to (x, y ) in its superview’s 
coordinates. Returns self. 

See also: - moveTo:: (View) 
rawScroll: 

- rawScroll: (const NXPoint *)newOrigin 

Performs scrolling of the document view. This method sets the ClipView’s bounds 
rectangle origin to newOrigin. Then, it copies as much of the previously visible 
document as possible, unless it received a setCopyOnScroll:NO message. It then 
sends its document view a message to either display or mark as invalidated the newly 
exposed region(s) of the Clip View. By default it will invoke the document view’s 
display:: method, but if the Clip View received a setDispIayOnScroll:NO message, it 
will invoke the document view’s invalidate:: method. The rawScroll: method does 
not send a reflectScrolI: message to its superview; that message is sent by the method 
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that invokes rawScroIl:. Note also that while the Clip View provides clipping to its 
frame, it does not clip to the update rectangles. 

This method is used by a private method through which all scrolling passes, and is 
invoked if the Clip View’s superview does not implement the scrollCliprto: method. If 
the Clip View’s superview does implement scrollClip:to:, that method should invoke 
rawScroll:. The ClipView’s typical superview (Scrollview) doesn’t implement the 
scrollCliprto: method. This mechanism is provided so that the ClipView’s superview 
can coordinate scrolling of multiple tiled Clip Views. Returns self. 

read: 

- read:(NXTypedStream *)stream 

Reads the Clip View and its document view from the typed stream stream. Returns self. 
See also: - write: 

resetCursorRects 

- resetCursorRects 

Resets the cursor rectangle for the document view to the bounds of the Clip View. 
Returns self. 

See also: - setDocCursor:, - addCursorRectrcursor: (View) 
rotate: 

- rotate :(NXCoord)^«g/^ 

Disables rotation of the ClipView’s coordinate system. You also should not rotate the 
ClipView’s document view, nor should you install a Clip View as a subview of a rotated 
view. The proper way to rotate objects in the document view is to perform the rotation 
in your document view’s drawSelf:: method. Returns self. 

rotateTo: 

- rotateTo: (NXCoord)angle 

Disables rotation of the ClipView’s frame rectangle. This method also disables 
ClipView’s inherited rotateBy: method. Returns self. 

See also: - rotate: 
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scale:: 


- scale: (NXCoord)x :(NXCoord)>’ 

Rescales the Clip View’s coordinate system by a factor of x for its x axis, and by a factor 
of y for its y axis. Since the document view’s coordinate system is measured relative 
to the Clip View’s coordinate system, the document view is redisplayed and a 
reflectScroll: message may be sent to the Clip View’s superview. Returns self. 

See also: - reflectScroll: (ScrollView) 

setBackgroundColor: 

- setBackgroundColor:(NXColor)co/<9r 

Sets the color of the Clip View’s background. This color is used to fill the area inside 
the Clip View that’s not covered by opaque portions of the document view. If no 
background gray has been set for the Clip View, this method sets it to the gray 
component of the color. Returns self. 

See also: - backgroundColor, - backgroundGray, - setBackgroundGray, 
NXGrayComponent() 

setBackgroundGray: 

- setBackgroundGray: (float)v< 2 /Me 

Sets the gray value of the Clip View’s background. This gray is used to fill the area 
inside the Clip View that’s not covered by opaque portions of the document view, value 
must lie in the range from 0.0 (black) to 1.0 (white). Returns self. 

See also: - backgroundColor, - backgroundGray, - setBackgroundColor 

setCopyOnScroll: 

- setCopyOnScroll :(BOOL)flag 

Determines whether the buffered bits will be copied when scrolling occurs. If flag is 
YES, scrolling will copy as much of the Clip View’s bitmap as possible to scroll the 
view, and the document view is responsible only for updating the newly exposed 
portion of itself. If flag is NO, the document view is responsible for updating the entire 
Clip View. This should only rarely be changed from the default value (YES). Returns 
self. 
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setDisplay OnScroll: 

- setDisplayOnScroll:(BOOL)/fog 

Determines whether the results of scrolling will be immediately displayed. If flag is 
YES, the results of scrolling will be immediately displayed. If flag is NO, the Clip View 
is marked as invalid but is not displayed. In either case, when a scroll occurs, the 
Clip View first copies as much of its buffered bitmap as possible, assuming the default 
case where setCopyOnScroll:YES was sent. This should only rarely be changed from 
the default value (YES). Returns self. 

See also: - rawScroll:, - display:: (View), - invalidate:: (View) 

setDocCursor: 

- setDocCursorianObj 

Sets the cursor to be used inside the ClipView’s bounds. anObj should be a NXCursor 
object. Returns the old cursor. 

setDocView: 

- setDocView:<2V7ew 

Sets aView as the ClipView’s document view. There is one document view per 
Clip View, so if there was already a document view for this Clip View it is replaced. This 
method initializes the document view with 

notifyAncestorWhenFrameChanged:YES and notifyWhenFlipped:YES 

messages. The origin of the document view’s frame is initially set to be coincident with 
the origin of the ClipView’s bounds. If the Clip View is contained within a Scroll View, 
you should send the ScrollView the setDocView: message and have the ScrollView 
pass this message on to the Clip View. Returns the old document view, or nil if there 
was none. 

See also: - setDocView: (ScrollView) 

setDrawOrigin:: 

- setDrawOrigin :(NXCoord)x :(NXCoord)y 

Overrides the View method so that changes in the ClipView’s coordinate system are 
reflected in the displayed document view. This method may redisplay the document 
view, and a reflectScroll: message may be sent to the ClipView’s superview. Returns 
self. 

See also: - setDrawOrigin:: (View) 
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setDrawRotation: 


- setDrawRotation :(NXCoord)a«g/e 

Disables rotation of the Clip View’s coordinate system. The proper way to rotate 
objects in the document view is to perform the rotation in your document view’s 
drawSelf:: method. Returns self. 

See also: - rotate: 

setDrawSize:: 

- setDrawSize : (NXCoord) : (NXCoord) height 

Overrides the View method so that rescaling of the Clip View’s coordinate system is 
reflected in the displayed document view. This method may redisplay the document 
view, and a reflectScroll: message may be sent to the Clip View’s superview. Returns 
self. 

See also: - setDrawSize:: (View) 
sizeTo:: 

- sizeTo: (NXCoord )width :(NXCoord )height 

Overrides the View method so that resizing of the Clip View’s frame rectangle is 
reflected in the displayed document view. This method may redisplay the document 
view, and a reflectScroll: message may be sent to the Clip View’s superview. Returns 
self. 


See also: - sizeTo:: (View) 
translate:: 

- translate :(NXCoord)jt :(NXCoord)y 

Overrides the View method so that translation of the Clip View’s coordinate system is 
reflected in the displayed document view. This method may redisplay the document 
view, and a reflectScroll: message may be sent to the Clip View’s superview. Returns 
self. 

See also: - translate:: (View) 


write: 

- write :(NXTypedStream *)stream 

Writes the receiving Clip View and its document view to the typed stream stream. 
Returns self. 

See also: - write: 
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METHODS IMPLEMENTED BY CLIPVIEW’S SUPERVIEW 

reflectScroll: 

- reflectScroll :aClipView 

Notifies the Clip View’s superview that either the Clip View’s bounds rectangle or the 
document view’s frame rectangle has changed, and that any indicators of the scroll 
position need to be adjusted. ScrollView implements this method to update its 
Scrollers. 

scrollClipito: 

- scrollClip :aClipView to:(const NXPoint *)newOrigin 

Notifies the Clip View’s superview that the Clip View needs to set its bounds rectangle 
origin to newOrigin. The Clip View’s superview should then send the Clip View the 
rawScroll: message. This mechanism is provided so that the ClipView’s superview 
can coordinate scrolling of multiple tiled Clip Views. Note that the default ScrollView 
class does not implement this method. 

See also: - rawScroll: (ClipView) 
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Control 


INHERITS FROM View : Responder : Object 

DECLARED IN appkit/Control.h 

CLASS DESCRIPTION 

Control is an abstract superclass that provides three fundamental features for 
implementing user interface devices. First, as a subclass of View, Control has a bounds 
rectangle in which to draw the on-screen representation of the device. Second, it 
provides a mouseDown: method and a position in the responder chain; together these 
features enable Control to receive and respond to user-generated events within its 
bounds. Third, it implements the sendAction:to: method through which Control sends 
an action message to its target object. Subclasses of Control defined in the Application 
Kit are Button, Form, Matrix, NXBrowser, NXColorWell, Slider, Scroller, and 
TextField. 

Target objects and action methods provide the mechanism by which Controls interact 
with other objects in an application. A target is an object that a Control has affect over. 
An action method is defined by the target class to enable its instances to respond to user 
input; the id of the Control is the only argument to the action method. When it receives 
an action message, a target can use the id to send a message requesting additional 
information from the Control about its status. Targets and actions can be set explicitly 
by application code. You can also set the target to nil and allow it to be determined at 
run time. When the target is nil, the Control that’s about to send an action message 
must look for an appropriate receiver. It conducts its search in a prescribed order: 

• It begins with the first responder in the current key window and follows 
nextResponder links up the responder chain to the Window object. After the 
Window object, it tries the Window’s delegate. 

• If the main window is different from the key window, it then starts over with the 
first responder in the main window and works its way up the main window’s 
responder chain to the Window object and its delegate. 

• Next, it tries the Application object, NXApp, and finally the Application object’s 
delegate. NXApp and its delegate are the receivers of last resort. 

Control provides methods for setting and using the target object and action method. 
However, these methods require that Control’s cell instance variable be set to some 
subclass of Cell that provides the instance variables target and action, such as 
ActionCell and its subclasses. 

Target objects and action methods demonstrate the close relationship between Controls 
and Cells. In most cases, a user interface device consists of an instance of a Control 
subclass paired with one or more instances of a Cell subclass. Each implements 
specific details of the user interface mechanism. For example, Control’s mouseDown: 
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method sends a trackMouse:inRect:ofView: message to Cell, which handles 
subsequent mouse and keyboard events; Cell sends Control a send Action :to: message 
in response to particular events. Control’s drawSelf:: method is implemented by 
sending a drawSelfrinView: message to Cell. As another example, Control provides 
methods for setting and formatting its contents; these methods send corresponding 
messages to Cell, which owns the contents instance variable. 

A Control subclass doesn’t have to use a Cell subclass to implement itself; Scroller and 
NXColorWell don’t. However, such subclasses have to take care of details that Cell 
would otherwise handle. Specifically, they have to overwrite methods designed to work 
with a Cell. What’s more, they cannot be used in a Matrix—a subclass of Control 
designed specifically for managing multiple Cell arrays such as radio buttons. You 
usually implement a unique user interface device by creating a subclass of Cell or 
ActionCell rather than Control. 

In general, Interface Builder is the easiest way to add both kit-defined and your own 
subclasses of Control to an application. 

The initFrame: method is the designated initializer for the Control class. Override this 
method if you create a subclass of Control that performs its own initialization. 

See also: ActionCell, Cell 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Declared in Control 

int 

tag; 


id 

struct _conFlags{ 

cell; 


unsigned int 

enabled: 1; 


unsigned int 

editingValid:l; 


unsigned int 

ignoreMultiClick: 1; 


unsigned int 

calcSize:l; 


} 

conFlags; 


tag An integer that identifies the Control; can be used 

by View’s findViewWithTag: method to find a 
Control in a view hierarchy. 
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cell 

conFlags.enabled 

conFlags.editing Valid 
conFlags.ignoreMultiClick 


The id of the Control’s cell (if it has only one). 

True if the Control is enabled; relevant for 
multi-cell controls only. 

True if editing has been validated. 

True if the Control ignores double- or 
triple-clicks. 


conFlags.calcSize 


True if the cell should recalculate its size and 
location before drawing. 


METHOD TYPES 

Initializing and freeing a Control 

Setting the Control’s Cell 

Enabling and disabling the Control 
Identifying the selected Cell 
Setting the Control’s value 


Formatting text 

Managing the field editor 


- initFrame: 

- free 

- cell 

- setCell: 

+ setCellClass: 

- isEnabled 

- setEnabled: 

- selectedCell 

- selectedTag 

- setFloat Value: 

- float Value 

- setDoubleValue: 

- double Value 

- setlnt Value: 

- int Value 

- setString Value: 

- setStringValueNoCopy: 

- setStringValueNoCopy: shouldFree: 

- string Value 

- setFont: 

- font 

- setAlignment: 

- alignment 

- setFloatingPointFormat:left:right: 

- abortEditing 

- currentEditor 

- validateEditing 


Application Kit Classes: Control 


2-181 



Managing the cursor 


- resetCursorRects 


Interacting with other Controls 

- takeDoubleValueFrom: 

- takeFloatValueFrom: 

- takelntValueFrom: 

- takeString ValueFrom: 

Resizing the Control 

- calcSize 

- sizeTo:: 

- sizeToFit 

Displaying the Control and Cell 

- drawCell: 

- drawCelllnside: 

- drawSelf:: 

- selectCell: 

- update 

- updateCell: 

- updateCelllnside: 

Target and action 

- action 

- isContinuous 

- sendAction:to: 

- sendActionOn: 

- set Action: 

- setContinuous: 

- setTarget: 

- target 

Assigning a tag 

- setTag: 

-tag 

Tracking the mouse 

- ignoreMultiClick: 

- mouseDown: 

- mouseDownFlags 

Archiving 

- read: 

- write: 


CLASS METHODS 


setCellClass: 

+ setCellClass:c/oss/d 


This abstract method does nothing and returns the id of the receiver. It’s implemented 
by subclasses of Control, which use this method to set their cell instance variable. 
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INSTANCE METHODS 


abortEditing 

- abortEditing 

Terminates and discards any editing of text displayed by the receiving Control. Returns 
self or, if no editing was going on in the receiving Control, nil. Does not redisplay the 
old value of the Control—you must explicitly do that. 

See also: - endEditingFor: (Window), - validateEditing 
action 

- (SEL)action 

Returns the action message sent by the Control. To get the action message, this method 
sends an action message to the Control’s cell. 

See also: - setAction: 


alignment 

- (int)alignment 


Returns the justification mode. The return value can be one of three constants: 
NX_LEFTALIGNED, NX_CENTERED or NX_RIGHTALIGNED. 


calcSize 
- calcSize 

Recomputes any internal sizing information for the Control, if necessary, by invoking 
calcDrawInfo: on its cell. This can be useful for caching any information needed to 
make the drawing of a cell faster. Does not draw. Can be used for more sophisticated 
sizing operations as well (for example, Form). This is automatically invoked whenever 
the Control is displayed and something has changed (as recorded by the calcSize flag). 

See also: - calcSize (Matrix, Form), - sizeToFit 


cell 

-cell 

Returns the Control’s cell. Should not be used by the action method of the target of the 
Control (use selectedCell). 
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currentEditor 

- currentEditor 

If the receiving Control is being edited (that is, the user is typing or selecting text in the 
Control), this method returns the editor (the Text object) being used to perform that 
editing. If the Control is not being edited, this method returns nil. 

double Value 

- (double)double Value 

Returns the value of the Control as a double-precision floating point number. If the 
Control contains many cells (for example, Matrix), then the value of the currently 
selectedCell is returned. If the Control is in the process of editing the affected cell, then 
validateEditing is invoked before the value is extracted and returned. 

See also: - setDoubleValue: 

drawCell: 

- drawCell :aCell 

If aCell is the cell used to implement this Control, then the Control is displayed. This 
is provided primarily in support of a consistent interface with a multiple cell Control’s 
drawCell:. Returns self. 

See also: - drawCell: (Matrix), - updateCell: 

drawCelllnside: 

- drawCellInside:aCe// 

Same as drawCell: except that only the “inside” of the Control is drawn (using the 
cell’s drawInside:inView: method). This method is used by setStringValue: and 
similar content-setting methods to provide a minimal update of the Control when its 
value is changed. Returns self. 

See also: - drawInsideiinView: (Cell), - drawCelllnside: (Matrix), 

- updateCelllnside: 

drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

Draws the Control. It simply invokes the Control’s cell’s drawSelf: in View: method. 
Must override if you have a multi-cell control. Returns self. 


2-184 Chapter 2: Class Specifications 



float Value 

- (float)floatValue 

Returns the value of the Control as a single-precision floating point number (see 
double Value for more details). 

See also: - setFloatValue: 

font 

- font 

Returns the font object used to draw the text (if any) of the Control. 

free 

- free 

Frees the memory used by the Control and its cells. Aborts editing if the text of the 
Control was currently being edited. Returns nil. 

ignoreMultiClick: 

- ignoreMultiClick: (BOOL)flag 

Sets the Control to ignore multiple clicks if flag is YES. By default, double-clicks (and 
higher order clicks) are treated the same as single clicks. You can use this method to 
“debounce” a control. 

initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes and returns the receiver, a new instance of Control, by setting frameRect as 
its frame rectangle. Sets the new instance as opaque. Since Control is an abstract class, 
messages to perform this method should appear only in subclass methods. initFrame: 
is the designated initializer for the Control class. 

int Value 

- (int)intValue 

Returns the value of the Control as an integer (see double Value for more details). 

See also: - setlntValue: 
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isContinuous 


- (BOOL)isContinuous 

Returns YES if the Control continuously sends its action to its target during mouse 
tracking. 

See also: - setContinuous: 

isEnabled 

- (BOOL)isEnabled 

Returns YES if the Control is enabled, NO otherwise. 

mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Invoked when the mouse button goes down while the cursor is within the bounds of the 
Control. The Control is highlighted and the Control’s Cell tracks the mouse until it 
goes outside the bounds, at which time the Control is unhighlighted. If the cursor goes 
back into the bounds, then the Control highlights again and its Cell starts tracking 
again. This behavior continues until the mouse button goes up. If it goes up with the 
cursor in the Control, the state of the Control is changed, and the action is sent to the 
target. If the mouse button goes up with the cursor outside the Control, no action is 
taken. 

mouseDownFIags 

- (int)mouseDownFlags 

Returns the event flags (for example, NX_SHIFTMASK) that were in effect at the 
beginning of tracking. The flags are valid only in the action method that is sent to the 
Control’s target. 

See also: - mouseDownFIags (Cell), - sendActionrto: 
read: 

- read:(NXTypedStream *)stream 

Reads the Control from the specified typed stream stream. 
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resetCursorRects 

- resetCursorRects 

If the Control’s cell is editable, then resetCursorRectiinView: is sent to the cell 
(which will, in turn, send addCursorRecticursor: back to the Control). Causes the 
cursor to be an I-beam when the mouse is over the editable portion of the cell. 

selectCell 

- selectCel V.aCell 

If aCell is the receiving Control’s cell and is currently unselected, this method selects 
aCell and redraws the Control. Returns self. 

selectedCell 

- selectedCell 

This method should be used by the target of the Control when it wants to get the cell of 
the sending Control. Note that even though the cell method will return the same value 
for single cell Controls, it’s strongly suggested that this method be used since it will 
work both for multiple and single cell Controls. 

See also: - sendActionrto:, - selectedCell (Matrix) 

selectedTag 

- (int)selectedTag 

The action method in the target of the Control should use this method to get the 
identifying tag of the sending Control’s cell. You should use the setTag: and tag 
methods in conjunction with findViewWithTag:. This is equivalent to [[self 
selectedCell] tag]. Returns -1 if there is no currently selectedCell. The cell’s tag can 
be set with ActionCell’s setTag: method. When you set a single-cell Control’s tag in 
Interface Builder, it sets both the Control’s and the cell’s tag (as a convenience). 

See also: - sendActionrto: 
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sendAction:to: 


- sendAction:(SEL)^Mcn'0« to itheTarget 

Sends a sendActionrto: message to NXApp, which in turn sends a message to 
theTarget to perform the Action. This method adds the Control’s id as the action 
method’s only argument. If theAction is NULL, no message is sent. 

This method is invoked primarily by Cell’s trackMouse:inRect:ofView:. 

If theTarget is nil, NXApp looks for an object that can respond to the message—that is, 
for an object that implements a method matching the theAction selector. It begins with 
the first responder of the key window. If the first responder can’t respond, it tries the 
first responder’s next responder and continues following next responder links up the 
responder chain. If none of the objects in the key window’s responder chain can handle 
the message and if the main window is different from the key window, it begins again 
with the first responder in the main window. If objects in neither the key window nor 
the main window can respond, NXApp tries to handle the message itself. If NXApp 
cannot respond, then the message is sent to NXApp’s delegate. 

Returns nil if the message could not be delivered; otherwise returns self. 

See also: - setAction:, - setTarget:, - trackMouse:inRect:ofView: (Cell) 

sendActionOn: 

- (int)sendActionOn:(int)/ms£ 

Sets a mask of the events that cause sendActionrto: to be invoked during tracking of 
the mouse (done in Cell’s trackMouse:inRect:ofView:). Returns the old event mask. 

See also: - sendActionOn: (Cell), - trackMouse:inRect:ofView: (Cell) 
setAction: 

- setAction :(SEL)aSelector 

Makes aSelector the Control’s action method. 

See also: - sendActionrto: 

setAlignment: 

- setAlignment: (mt)mode 

Sets the justification mode. The mode should be one of: NX_LEFTALIGNED, 
NX_CENTERED or NX_RIGHTALIGNED. 
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setCell: 

- setCell :aCell 

Sets the cell of the Control to be cell. Use this method with great care as it can 
irrevocably damage your Control. Returns the old cell. 

setContinuous: 

- setContinuous :(BOOL)j flag 

Sets whether the Control should continuously send its action to its target as the mouse 
is tracked. 

See also: - setContinuous: (ButtonCell, SliderCell), - sendActionOn: 

setDouble Value: 

- setDoubleValue:(double)tfD<9wb/e 

Sets the value of the Control to be aDouble (a double-precision floating point number). 
If the Control contains many cells, then the currently selectedCell’s value is set to 
aDouble. If the affected cell is currently being edited, then that editing is aborted and 
the value being typed is discarded in favor of aDouble. If autodisplay is on, then the 
cell’s “inside” is redrawn. 

See also: - double Value, - abortEditing, - drawInside:inView: (Cell) 

setEnabled: 

- setEnabled :(BOOL)flag 

Sets the flag determining whether the Control is active or not. Redraws the entire 
Control if autodisplay is on. Subclasses may want to override this to redraw only a 
portion of the Control when the enabled state changes (Button and Slider do this). 

setFloat Value: 

- setFloatValue:(float)<2f7<9£r 

Same as setDoubleValue:, but sets the value as a single-precision floating point 
number. 

See also: - float Value 
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setFloatingPointFormat:left:right: 

- setFloatingPointFormat: (BOOL )autoRange 

left ‘.(unsigned )leftDigits 
right : (unsigned)rz'g/ 2 rZ) igits 

Sets the floating point number format of the Control. Does not redraw the cell. Affects 
only subsequent settings of the value using setFloatValue:. 

See also: - setFloatPointFormat:left:right: (Cell) 

setFont: 

- setFon tifontObj 

Sets the font used to draw the text (if any) in the Control. You only need to invoke this 
method if you do not want to use the default font (Helvetica 12.0). If autodisplay is on, 
then the inside of the cell is redrawn. 

setlntValue: 

- setlntValue :{mt)anlnt 

Same as setDoubleValue:, but sets the value as an integer. 

See also: -intValue 

setString Value: 

- setString Value: (const char *)aString 

Same as setDoubleValue:, but sets the value as a string. 

See also: - string Value, - setString ValueNoCopy:, - setlntValue: 

setStr ing V alueN oCopy: 

- setString ValueNoCopy: (const char *)aString 

Like setStringValue:, but doesn’t copy the string. 

See also: - stringValue, - setStringValue:, - setStringValueNoCopy:shouldFree: 

setStringValueNoCopy:shouldFree: 

- setStringValueNoCopy :(char *)aString shouldFree:(BOOL)/?<a:g 

Like setStringValueNoCopy:, but lets you specify whether the string should be freed 
when the Control is freed. 

See also: - stringValue, - setStringValueNoCopy: 
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setTag: 

- setTag: (int)anlnt 

Makes anlnt the receiving Control’s tag. 

See also: - tag, - selectedTag, - findViewWithTag: (View) 

setTarget: 

- setTarget :anObject 

Sets the target for the Control’s action message. 

See also: - sendActionito: 

sizeTo:: 

- sizeTo:(NXCoord )width :(NXCoord )height 

Changes the width and the height of the Control’s frame. Redisplays the Control if 
autodisplay is on. 

sizeToFit 

- sizeToFit 

Changes the width and the height of the Control’s frame so that they get the minimum 
size to contain the cell. If the Control has more than one cell, then you must override 
this method. 

See also: - sizeToFit (Matrix), - sizeToCells (Matrix) 
stringValue 

- (const char *)stringValue 

Returns the value of the Control as a string (see double Value for more details). 

See also: - setStringValue:, - setStringValueNoCopy: 


tag 

- (int)tag 


Returns the receiving Control’s tag (not the Control’s cell’s tag). 
See also: - setTag:, - selectedTag 
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takeDoubleValueFrom: 

- takeDoubleValueFrom '.sender 

Sets the receiving Control’s double-precision floating-point value to the value obtained 
by sending a double Value message to sender. 

This method can be used in action messages between Controls. It permits one Control 
(sender) to affect the value of another Control (the receiver) by sending this method in 
an action message to the receiver. For example, a TextField can be made the target of 
a Slider. Whenever the Slider is moved, it will send a takeDoubleValueFrom: 
message to the TextField. The TextField will then get the Slider’s floating-point value, 
turn it into a text string, and display it, thus tracking the value of the Slider. 

See also: - setDouble Value:, - double Value 

takeFloat V alueFr om: 

- takeFloatValueFroimsera/er 

Sets the receiving Control’s single-precision floating-point value to the value obtained 
by sending a floatValue message to sender. 

See setDouble Value: for an example. 

See also: - setFloatValue:, - floatValue 

takelntValueFrom: 

- takelntValueFroimscwdcr 

Sets the receiving Control’s integer value to the value returned by sending an intValue 
message to sender. 

See setDouble Value: for an example. 

See also: - setlntValue:, - intValue 

takeString V alueFrom: 

- takeStringValueFrom: sender 

Sets the receiving Control’s character string to a string obtained by sending a 
stringValue message to sender. 

See setDouble Value: for an example. 

See also: - stringValue, - setStringValue: 
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target 

- target 

Returns the target for the Control’s action message. 

See also: - setTarget: 

update 

- update 

Same as View’s update, but also makes sure that calcSize gets performed. 

updateCell: 

- updateCell :aCell 

If aCell is a cell used to implement this Control, and if autodisplay is on, then draws 
the Control; otherwise, sets the needsDisplay and calcSize flags to YES. 

updateCelllnside: 

- updateCellInside:aCe// 

If aCell is a cell used to implement this Control, and if autodisplay is on, draws the 
inside portion of the cell; otherwise sets the needsDisplay flag to YES. 

validateEditing 

- validateEditing 

Causes the value of the field currently being edited (if any) to be absorbed as the value 
of the Control. Invoked automatically from string Value, int Value, and others, so that 
partially edited field’s values will be reflected in the values returned by those methods. 

This method doesn’t end editing; to do that, invoke Window’s endEditingFor: or 
abortEditing. 

See also: - endEditingFor: (Window) 
write: 

- write :(NXTypedStream *)stream 

Writes the Control to the specified typed stream stream. 
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INHERITS FROM 


Object 


DECLARED IN Font.h 


CLASS DESCRIPTION 

The Font class provides objects that correspond to PostScript fonts. Each Font object 
records a font’s name, size, style, and matrix. When a Font object receives a set 
message, it establishes its font as the current font in the Window Server’s current 
graphics state. 

For a given application, only one Font object is created for a particular PostScript font. 
When the Font class object receives a message to create a new object for a particular 
font, it first checks whether one has already been created for that font. If so, it returns 
the id of that object; otherwise, it creates a new object and returns its id. This system 
of sharing Font objects minimizes the number of objects created. It also implies that 
no one object in your application can know whether it has the only reference to a 
particular Font object. Thus, Font objects shouldn’t be freed; Font’s free method 
simply returns self. 

A Font object’s fontNum instance variable stores a number (a PostScript user object) 
that refers to the actual font dictionary within the Window Server. You shouldn’t 
change the value of this variable. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in Font 

char 

*name; 


float 

size; 


int 

style; 


float 

^matrix; 


int 

fontNum; 


NXFacelnfo 

*faceInfo; 


id 

struct _fFlags { 

otherFont; 


unsigned int 

usedByWS:l; 


unsigned int 

usedByPrinter: 1 


unsigned int 

isScreenFont: 1; 


} 

fFlags; 

name 

The font’s name. 


size 

The font’s size. 
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style 

matrix 

fontNum 

facelnfo 

otherFont 

fFlags.usedByWS 

fFlags.usedByPrinter 

fFlags.isScreenFont 

METHOD TYPES 

Initializing the Class object 

Creating and freeing a Font object 

Querying the Font object 


Setting the font 
Archiving 


The font’s style. 

The font’s matrix. 

The user object referring to this font. 

The font’s face information. 

The associated screen font for this font. 

True if the font is stored in the Window Server. 
True if the font is stored in the printer. 

True if the font is a screen font. 


+ initialize 
+ useFont: 

+ newFont:size: 

+ newFont:size:matrix: 

+ newFont:size:style:matrix: 

- free 

- fontNum 

- getWidthOf: 

- hasMatrix 

- matrix 

- metrics 

- name 

- points ize 

- readMetrics: 

- screenFont 

- style 

- set 

- setStyle: 

- awake 

- finishUnarchiving 

- read: 

- write: 
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CLASS METHODS 


alloc 

Disables the inherited alloc method to prevent multiple Font objects from being created 
for a single PostScript font. Create Font objects by using newFont:size:style:matrix:, 
newFont:size:matrix:, or newFont:size:. These methods ensure that no more than 
one Font object is created for any PostScript font. Returns an error message. 

See also: + newFont:size:style:matrix:, + newFont:size:matrix:, + newFont:size: 
allocFromZone: 

Disables the inherited allocFromZone: method to prevent multiple Font objects from 
being created for a single PostScript font. Create Font objects by using 
newFont:size:style:matrix:, newFont:size:matrix:, or newFont:size:. These 
methods ensure that no more than one Font object is created for any PostScript font. 
Returns an error message. 

See also: + newFont:size:style:matrix:, + newFont:size:matrix:, + newFont:size: 

initialize 
+ initialize 

Initializes the Font class object. The class object receives an initialize message before 
it receives any other message. You never send an initialize message directly. 

See also: + initialize (Object) 
newFont:size: 

+ newFont: (const char *)fontName size:(float )fontSize 

Returns a Font object for font fontName of siz efontSize. This method invokes the 
newFont:size:style:matrix: method with the style set to 0 and the matrix set to 
NX_FLIPPEDMATRIX. 

See also: + newFont:size:style:matrix:, + newFont:size:matrix: 
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newFont:size:matrix: 

+ newFont:(const char *)fontName 
s\ze:(fioat)fontSize 
matrix: (const float *)fontMatrix 

Returns a Font object for font fontName of size fontSize. This method invokes the 
newFont:size:style:matrix: method with the style set to 0. 

See also: + newFont:size:style:matrix:, + newFontrsize: 

newFont:size:sty!e:matrix: 

+ newFont:(const char *)fontName 
size: (ffodX)fontSize 
style:(ini)fontStyle 
matrix:(const float *)fontMatrix 

Returns a Font object for font fontName, of size fontSize, and matrix font Matrix. 
fontStyle is currently ignored. If an appropriate Font object was previously created, it’s 
returned; otherwise, a new one is created and returned. If an error occurs, this method 
returns nil. This is the designated new... method for the Font class. 

There are two constants available for th efontMatrix parameter: 

• NXJDENTITYMATRIX. Use the identity matrix. 

• NX_FLIPPEDMATRIX. Use a flipped matrix. (Appropriate for a flipped View 
like the Text object.) 

The fontStyle parameter is stored in the Font object, and is preserved by the 
FontManager’s convertFont: method, but is not used by the Application Kit. It can be 
used to store application-specific font information. 

Note: If this method is invoked from a subclass (through a message to super), a new 
object is always created. Thus, your subclass should institute its own system for 
sharing Font objects. 

See also: + newFont:size:matrix:, + newFont:size: 
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useFont: 

+ useFont:(const char *)fontName 

Registers that the font identified by fontName is used in the document. Returns self. 

The Font class object keeps track of the fonts that are being used in a document. It does 
this by registering the font whenever a Font object receives a set message. When a 
document is called upon to generate a conforming PostScript language version of its 
text (such as during printing), the Font class provides the list of fonts required for the 
% %DocumentFonts comment. (See Document Structuring Conventions by Adobe 
Systems Inc.) 

The useFont: method augments this system by providing a way to register fonts that 
are included in the document but not set using Font’s set method. Send a useFont: 
message to the class object for each font of this type. Returns self. 

See also: - set 


INSTANCE METHODS 

awake 
- awake 

Reinitializes the Font object after it’s been read in from a stream. This method makes 
sure that the Font object doesn’t assume it has data cached in the Window Server. 

An awake message is automatically sent to each object of an application after all 
objects of that application have been read in. You never send awake messages directly. 
The awake message gives the object a chance to complete any initialization that read: 
couldn’t do. If you override this method in a subclass, the subclass should send this 
message to its superclass: 


[super awake]; 

Returns self. 

See also: - read:, - write:, - finishUnarchiving 

finishUnarchiving 
- finishUnarchiving 

A finishUnarchiving message is sent after the Font object has been read in from a 
stream. This method checks if a Font object for the particular PostScript font already 
exists. If so, self is freed and the existing object is returned. 

See also: - read:, - write:, - awake 
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fontNum 


- (int)fontNum 

Returns the PostScript user object that corresponds to this font. The Font object must 
set the font in the Window Server before this method will return a valid user object. 
Sending a Font object the set message sets the font in the Window Server. The 
fontNum method returns 0 if the Font object hasn’t previously received a set message 
or if the font couldn’t be set. 

See also: - set, DPSDefineUserObjectO 

free 

- free 

Has no effect. Since only one Font object is allocated for a particular font, and since 
you can’t be sure that you have the only reference to a particular Font object, a Font 
object shouldn’t be freed. 


getWidthOf: 

- (float)getWidthOf: (const char *)string 

Returns the width of string using this font. This method has better performance than 
the Window Server routine PSstringwidth(). 

hasMatrix 

- (BOOL)hasMatrix 

Returns YES if the Font object’s matrix is different from the identity matrix, 
NX_IDENTITYMATRIX; otherwise, returns NO. 

See also: + newFont:size:style:matrix:, - matrix 
matrix 

- (const float *)matrix 

Returns a pointer to the matrix for this font. 

See also: - hasMatrix 


2-200 Chapter 2: Class Specifications 



metrics 


- (NXFontMetrics *)metrics 

Returns a pointer to the NXFontMetrics record for the font. See the header file 
appkit/afm.h for the structure of an NXFontMetrics record. 

See also: - readMetrics: 

name 

- (const char *)name 
Returns the name of the font. 

pointSize 

- (float)pointSize 

Returns the size of the font in points. 

read: 

- read:(NXTypedStream *)stream 

Reads the Font object’s instance variables from stream. A read: message is sent in 
response to archiving; you never send this message. 

See also: - write:, - read: (Object) 
readMetrics: 

- (NXFontMetrics *) readMetrics: {mt)flags 

Returns a pointer to the NXFontMetrics record for this font. The flags argument 
determines which fields of the record will be filled in. flags is built by ORing together 
constants such as NX_FONTHEADER, NX_FONTMETRICS, and 
NX_FONTWIDTHS. See the header file appkit/afm.h for the complete list of 
constants and for the structure of the NXFontMetrics record. 

See also: - metrics 

screenFont 

- screenFont 

Provides the screen font corresponding to this font. If the receiver represents a printer 
font, this method returns the Font object for the associated screen font (or nil if one 
doesn’t exist). If the receiver represents a screen font, it simply returns self. 
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set 


- set 

Makes this font the current font in the current graphics state. Returns self. 

When a Font object receives a set message, it registers with the Font class object that 
its PostScript font has been used. In this way, the Application Kit, when called upon to 
generate a conforming PostScript language document file, can list the fonts used within 
a document. (See Document Structuring Conventions by Adobe Systems Inc.) If the 
application uses fonts without sending set messages (say through including an EPS 
file), such fonts must be registered by sending the class object a useFont: message. 

See also: + useFont: 
setStyle: 

- setStyle :(mt)aStyle 

Sets the Font’s style. Setting a style isn’t recommended but is minimally supported— 
a Font object’s style isn’t interpreted in any way by the Application Kit. You can use 
it for your own non-PostScript language font styles (a drop-shadow style, for example). 

Be very careful using this method since it causes the Font to stop being shared. You 
must reassign the pointer to the Font to the return value of setStyle:. 

font = [font setStyle:12] ; 

Returns self. 

See also: - style 

style 

- (int)style 

Returns the style of the font. For Font objects created by the Application Kit, this 
method returns 0. 

See also: -setStyle: 
write: 

- write :(NXTypedStream *)stream 

Writes the Font object’s instance variables to stream. A write: message is sent in 
response to archiving; you never send this message directly. 

See also: - read:, - write: (Object) 
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CONSTANTS AND DEFINED TYPES 


/* Flipped matrix */ 

#define NX_IDENTITYMATRIX ((float *) 0) 

#define NX_FLIPPEDMATRIX ((float *) -1) 

/* Space characters */ 

#define NX_FIGSPACE ((unsigned short)0x80) 

/* Font information */ 
typedef struct _NXFaceInfo { 

NXFontMetrics *fontMetrics; /* Information from afm file. */ 
int flags; /* Which font info is present. */ 

struct _fontFlags { /* Keeps track of font usage for 

Conforming PS */ 

unsigned int usedInDoc:l; /* Has font been used in document?*/ 
unsigned int usedlnPage:1; /* Has font been used in page? */ 
unsigned int usedlnSheet:1; /* Has font been used in sheet? 

(There can be more than one 
page printed on a sheet of 
paper.) */ 

unsigned int _PADDING:13; 

} fontFlags; 

struct _NXFaceInfo *nextFInfo; /* Next record in list. */ 

} NXFacelnfo; 
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FontManager 


INHERITS FROM Object 

DECLARED IN FontManager.h 

CLASS DESCRIPTION 

The FontManager is the center of activity for font conversion. It accepts messages from 
font conversion user-interface objects (such as the Font menu or the Font panel) and 
appropriately converts the current font in the selection by sending a changeFont: 
message up the responder chain. When an object receives a changeFont: message, it 
should query the FontManager (by sending it a convertFont: message), asking it to 
convert the font in whatever way the user has specified. Thus, any object containing a 
font that can be changed should respond to the changeFont: message by sending a 
convertFont: message back to the FontManager for each font in the selection. 

To use the FontManager, you simply insert a Font menu into your application’s menu. 
This is most easily done with Interface Builder, but, alternatively, you can send a 
getFontMenu: message to the FontManager and then insert the menu that it returns 
into the application’s main menu. Once the Font menu is installed, your application 
automatically gains the functionality of both the Font menu and the Font panel. 

The FontManager can be used to convert a font or find out the attributes of a font. It 
can also be overridden to convert fonts in some application-specific manner. The 
default implementation of font conversion is very conservative: The font isn’t 
converted unless all traits of the font can be maintained across the conversion. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in FontManager 

id 

panel; 


id 

menu; 


SEL 

action; 


int 

whatToDo; 


NXFontTraitMask 

traitToChange; 


id 

struct _fmFlags { 

selFont; 


unsigned int 

multipleFont:!; 


unsigned int 

disabled; 1; 


} 

fmFlags; 

panel 

The Font panel. 


menu 

The Font menu. 
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action 


The action to send. 


whatToDo 

traitToChange 

selFont 

fmFlags.multipleFont 

fmFlags.disabled 

METHOD TYPES 

Creating the FontManager 
Converting fonts 


Setting parameters 

Querying parameters 


Target and action methods 

Archiving the FontManager 
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What to do when a convertFont: message is 
received. 

The trait to change if whatToDo == 

NX_CH AN GETR AIT. 

The font of the current selection. 

True if the current selection has multiple fonts. 

True if the Font panel and menu are disabled. 


+ new 

- convertFont: 

- convertWeight:of: 

- convert: toFamily: 

- convert:toHaveTrait: 

- convert.toNotHaveTrait: 

- findFont:traits:weight:size: 

- getFamily:traits:weight:size:ofFont: 

- setAction: 

+ setFontPanelFactory: 

- setSelFont:isMultiple: 

- setEnabled: 

- action 

- availableFonts 

- getFontMenu: 

- getFontPanel: 

- isMultiple 

- selFont 

- isEnabled 

- modifyFont: 

- addFontTrait: 

- removeFontTrait: 

- modifyFontViaPanel: 

- orderFrontFontPanel: 

- sendAction 

- finishUnarchiving 



CLASS METHODS 


alloc 

Disables the inherited alloc method to prevent multiple FontManagers from being 
created. There’s only one FontManager object for each application; you access it using 
the new method. Returns an error message. 

See also: + new 

allocFromZone: 

Disables the inherited allocFromZone method to prevent multiple FontManagers from 
being created. There’s only one FontManager object for each application; you access 
it using the new method. Returns an error message. 

See also: + new 

new 
+ new 

Returns a FontManager object. An application has no more than one FontManager 
object, so this method either returns the previously created object (if it exists) or creates 
a new one. This is the designated new method for the FontManager class. 

setF ontPanelFactory: 

+ setFontPanelF actory ‘.factoryId 

Sets the class object that will be used to create the FontPanel object when the user 
chooses Font Panel from the Font menu and no Font panel has yet been created. Unless 
you use this method to specify another class, the FontPanel class will be used. 


INSTANCE METHODS 

action 

- (SEL)action 

Returns the action that’s sent to the first responder when the user selects a new font 
from the Font panel or from the Font menu. 

See also: - set Action; 
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addFontTrait: 

- addFontTraitr^rafer 

Causes the FontManager’s action message (by default, changeFont:) to be sent up the 
responder chain. When the responder replies with a convertFont: message, the font is 
converted to add the trait specified by sender. 

Before the action message is sent up the responder chain, the FontManager sets its 
traitToChange variable to the value returned by sending sender a selectedTag 
message. The FontManager also sets its whatToDo variable to NX_ADDTRAIT. 
When the convertFont: message is received, the FontManager converts the supplied 
font by sending itself a convert'.toHaveTrait: message. 

See also: - removeFontTrait:, - convertFont:, - convert:toHaveTrait:, 

- selectedTag (Control) 


availableFonts 

- (char **)availableFonts 

Returns by reference a NULL-terminated list of NULL-terminated PostScript font 
names of all the fonts available for use by the Window Server. The returned names are 
suitable for creating new Fonts using the newFont:size: class method of the Font class. 
The fonts are not in any guaranteed order, but no font name is repeated in the list. It’s 
the sender’s responsibility to free the list when finished with it. 

See also: + newFont:size: (Font) 
convertitoFamily: 

- convert ifontObj toFamily: (const char *)family 

Returns a Font object whose traits are the same as those of fontObj except as specified 
by family. If the conversion can’t be made, the method returns fontObj itself. This 
method can be used to convert a font, or it can be overridden to convert fonts in a 
different manner. 

See also: - convert:toHaveTrait:, convertWeight:of: 
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convert:toHaveTrait: 

- convert ifontObj toHaveTrait:(NXFontTraitMask)fra/^ 

Returns a Font object whose traits are the same as those of fontObj except as altered by 
the addition of the traits specified by traits. Of course, conflicting traits (such as 
NX_CONDENSED and NX_EXPANDED) have the effect of turning each other off. 
If the conversion can’t be made, the method returns fontObj itself. This method can be 
overridden to convert fonts in a different manner. 

See also: - convert:toNotHaveTrait:, - convertrtoFamily:, - convertWeight:of: 
convert:toNotHaveTrait: 

- convert fontObj toNotHaveTrait:(NXFontTraitMask)fra/ts 

Returns a Font object whose traits are the same as those of fontObj except as altered by 
the removal of the traits specified by traits. If the conversion can’t be made, the method 
returns fontObj itself. This method can be overridden to convert fonts in a different 
manner. 

See also: - convertitoHaveTrait:, - convert:toFamily:, - convertWeightiof: 

convertFont: 

- convertFont fontObj 

Converts fontObj according to the user’s selections from the Font panel or menu. 
Whenever you receive a changeFont: message from the FontManager, you should send 
a convertFont: message for each font in the selection. 

This method determines what to do to the fontObj by checking the whatToDo instance 
variable and applying the appropriate conversion method. Returns the converted font. 

convertWeight:of: 

- convertWeight: (BOOL)upFlag ofifontObj 

Attempts to increase (if upFlag is YES) or decrease (if upFlag is NO) the weight of the 
font specified by fontObj. If it can, it returns a new font object with the higher (or 
lower) weight. If it can’t, it returns fontObj itself. By default, this method converts the 
weight only if it can maintain all of the traits of the original fontObj. This method can 
be overridden to convert fonts in a different manner. 

See also: - convertitoHaveTrait:, - convert:toNotHaveTrait:, - convert:toFamily: 
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findFont:traits:weight:size: 

- findFont: (const char *)family 

traits: (NXFontTraitMask)fra//s 
weight: (int )weight 
size: (float )size 

If there’s a font on the system with the specified family, traits , weight, and size , then it’s 
returned; otherwise, nil is returned. If NX_BOLD or NX_UNBOLD is one of the 
traits, weight is ignored. 


finishUnarchiving 

- finishUnarchiving 

Finishes the unarchiving task by instantiating the one application-wide instance of the 
FontManager class if necessary. 

getF amily: traits: weight :size :ofFont: 

- getFamily: (const char **)family 

traits: (NXFontTraitMask *)traits 
weight:(int *)weight 
size:(float*)s/z<? 
ofFont ifontObj 

For the given font object fontObj, copies the font family, traits, weight, and point size 
information into the storage referred to by this method’s arguments. 

getFontMenu: 

- getFontMenu:(BOOL)crca/e 

Returns a menu suitable for insertion in an application’s menu. The menu contains an 
item that brings up the Font panel as well as some common accelerators (such as Bold 
and Italic). If the create flag is YES, the menu is created if it doesn’t already exist. 

See also: - getFontPanel: 


2-210 Chapter 2: Class Specifications 



getFontPanel: 

- getFontPanel: (BOOL)create 

Returns the FontPanel that will be used when the user chooses the Font Panel command 
from the Font menu. If the create flag is YES, the FontPanel is created if it doesn’t 
already exist. 

Unless you’ve specified a different class (by sending a setFontPanelFactory : message 
to the FontManager class before creating the FontManager object), an object of the 
FontPanel class is returned. 

See also: - getFontMenu: 

isEnabled 

- (BOOL)isEnabled 

Reports whether the controls in the Font panel and the commands in the Font menu are 
enabled or disabled. 

See also: - setEnabled: 

isMultiple 

- (BOOL)isMultiple 

Returns whether the current selection has multiple fonts. 

modifyFont: 

- modifyFont '.sender 

Causes the FontManager’s action message (by default, changeFont:) to be sent up the 
responder chain. When the responder replies with a convertFont: message, the font is 
converted in a way specified by the selectedTag of the sender of this message. The 
Larger, Smaller, Heavier, and Lighter commands in the Font menu invoke this method. 

See also: - addFontTrait:, - removeFontTrait: 
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modify Fon tV iaPanel: 

- modifyFontViaPanelrsemfer 

Causes the FontManager’s action message (by default, changeFont:) to be sent up the 
responder chain. When the receiver replies with a convertFont: message, the 
FontManager sends a panelConvertFont: message to the FontPanel to complete the 
conversion. 

This message is almost always sent by a Control in the Font panel itself. Usually, the 
panel uses the FontManager’s convert routines to do the conversion based on the 
choices the user has made. 

See also: - panelConvertFont: (FontPanel) 

or derFrontFontPanel: 

- orderFrontFontPanelsender 

Sends orderFront: to the FontPanel. If there’s no Font panel yet, a new message is 
sent to the FontPanel class object, or to the object you specified with the FontManager’s 
setFontPanelFactory: class method. 

removeFontTrait: 

- removeFontTraitrsmier 

Causes the FontManager’s action message (by default, changeFont:) to be sent up the 
responder chain. When the responder replies with a convertFont: message, the font is 
converted to remove the trait specified by sender. 

Before the action message is sent up the responder chain, the FontManager sets its 
traitToChange variable to the value returned by sending sender a selectedTag 
message. The FontManager also sets its whatToDo variable to NX_REMOVETRAIT. 
When the convertFont: message is received, the FontManager converts the supplied 
font by sending itself a convert:toNotHaveTrait: message. ' 

See also: - convertFont:, - convertrtoHaveTrait:, - selectedTag (Control) 
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selFont 


- selFont 

Returns the last font set with setSelFont:isMultiple:. 

If you receive a changeFont: message from the FontManager and want to find out what 
font the user has selected from the Font panel, use the following (assuming 
theFontManager is the application’s FontManager object): 


selectedFont = [theFontManager convertFont:[theFontManager selFont]] 


See also: - setSelFont:isMultiple:, - modifyFont: 

sendAction 

- sendAction 

Sends the FontManager’s action message (by default, changeFont:) up the responder 
chain. The sender is always the FontManager object regardless of which user-interface 
object initiated the sending of the action. The whatToDo and possibly traitToChange 
variables should be set appropriately before sending a sendAction message. 

You rarely, if ever, need to send a sendAction message or to override this method. The 
message is sent by the target/action messages sent by different user-interface objects 
that allow users to manipulate the font of the current text selection (for example, the 
Font panel and the Font menu). 

See also: -setAction: 
set Action: 

- setAction:(SEL)<2Se/ecfor 

Sets the action that’s sent when the user selects a new font from the Font panel or from 
the Font menu. The default is changeFont:. 

See also: - sendAction 
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setEnabled: 

- setEnabled:(BOOL)/7<2£ 

Sets whether the controls in the Font panel and the commands in the Font menu are 
enabled or disabled. By default, these controls and commands are enabled. Even when 
disabled, the Font panel allows the user to preview fonts. However, when the Font 
panel is disabled, the user can’t apply the selected font to text in the application’s main 
window. 

You can use this method to disable the user interface to the font selection system when 
its actions would be inappropriate. For example, you might disable the font selection 
system when your application has no document window. 

See also: - isEnabled 

setSeIFont:isMultiple: 

- setSelFont:/<9«?0£>y' isMultiple:(BOOL)/fag 

Sets the font that the Font panel is currently manipulating. An object containing a 
document should send this message every time its selection changes. If the selection 
contains multiple fonts, flag should be YES. 

An object shouldn’t send this message as part of its handling of a changeFont: 
message, since doing so will cause subsequent convertFont: messages to have no 
effect. This is because if you are converting a font based on what is set in the Font panel 
and you reset what’s in the panel (by sending a setSelFontiisMultiple: message), the 
FontManager can no longer sensibly convert the font since the information necessary 
to convert it has been lost. 

See also: - selFont 
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CONSTANTS AND DEFINED TYPES 


typedef unsigned int NXFontTraitMask; 


/* 

* Font Traits. This list should be kept small since the more traits 

* that are assigned to a given font, the harder it will be to map it 

* to some other family. Some traits are mutually exclusive, such as 

* NX_EXPANDED and NX_CONDENSED. 

*/ 

#define NX_ITALIC 0x00000001 

#define NX_BOLD 0x00000002 

#define NX_UNBOLD 0x00000004 

#define NX_NONSTANDARDCHARSET 0x00000008 

♦define NX_NARROW 
#define NX_EXPANDED 
#define NX_CONDENSED 
#define NX_SMALLCAPS 
#define NX_POSTER 
#define NX COMPRESSED 


0x00000010 

0x00000020 

0x00000040 

0x00000080 

0x00000100 

0x00000200 


/* whatToDo values */ 

♦define NX_NOFONTCHANGE 0 
♦define NX_VIAPANEL 1 
♦define NX_ADDTRAIT 2 
♦define NX_SIZEUP 3 
♦define NX_SIZEDOWN 4 
♦define NX_HEAVIER 5 
♦define NX_LIGHTER 6 
♦define NX REMOVETRAIT 7 
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FontPanel 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN FontPanel.h 


CLASS DESCRIPTION 

The FontPanel is a user-interface object that lets the user preview 
font of the text that’s selected in the application’s main window, 
are made through conversion messages sent to the FontManager. 

FontPanel object for each application. 

In general, you add the facilities of the FontPanel (and of the other components of the 
font conversion system: the FontManager and the Font menu) to your application 
through Interface Builder. You do this by dragging a Font menu into one of your 
application’s menus. At runtime, when the user chooses the Font Panel command for 
the first time, the FontPanel object will be created and hooked into the font conversion 
system. You can also create (or access) the FontPanel through either of the new... 
methods. 

A FontPanel can be customized by adding an additional View object or hierarchy of 
View objects (see setAccessoryView:). If you want the FontManager to instantiate a 
panel object from some class other than FontPanel, use the FontManager’s 
setFontPanelFactory: method. 


fonts and change the 
The actual changes 
There is only one 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from Window 

NXRect 

frame; 


id 

contentView; 


id 

delegate; 


id 

firstResponder; 


id 

lastLeftHit; 


id 

lastRightHit; 


id 

counterpart; 


id 

fieldEditor; 


int 

winEventMask; 


int 

windowNum; 


float 

backgroundGray; 


struct _wFlags 

wFlags; 


struct _wFlags2 

wFlags2; 

Inherited from Panel 

(none) 
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Declared in FontPanel 


id 

faces; 

id 

families; 

id 

preview; 

id 

current; 

id 

size; 

id 

sizes; 

id 

manager; 

id 

selFont; 

NXFontMetrics 

*selMetrics; 

int 

curTag; 

id 

accessory View; 

id 

setButton; 

id 

separator; 

id 

sizeTitle; 

char 

*lastPreview; 

struct _fpFlags { 


unsigned int 

multipleFont 

unsigned int 

dirty:1; 

} 

fpFlags; 


faces 

The typeface browser. 

families 

The Family browser. 

preview 

The preview field. 

current 

The current font field. 

size 

The Size field. 

sizes 

The Size browser. 

manager 

The FontManager object. 

selFont 

The font of the current selection. 

selMetrics 

The metrics of selFont. 

curTag 

The tag of the currently displayed font. 

accessory View 

The application-customized area. 

currentBox 

The box displaying the current font. 

setButton 

The Set button. 

separator 

The line separating buttons from upper part of 
panel. 

sizeTitle 

The title over the Size field and Size browser. 
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lastPreview 
fpFlags.multipleFont 
fpFlags.dirty 


The last font previewed. 

True if selection has multiple fonts. 

True if panel was updated while not visible. 


METHOD TYPES 

Creating a FontPanel + new 

+ newContent:style:backing:buttonMask:defer: 

Setting the font - panelConvertFont: 

- setPanelFontrisMultiple: 

Configuring the FontPanel - accessory View 

- set Accessory View: 

- setEnabled: 

- isEnabled 

- worksWhenModal 

Editing the FontPanel’s fields - textDidGetKeysrisEmpty: 

- textDidEnd:endChar: 

- orderWindow:relativeTo: 

- windowDidResize: 

- windowWillResizeitoSize: 


Displaying the FontPanel 
Resizing the FontPanel 


CLASS METHODS 

alloc 

Disables the inherited alloc method to prevent multiple FontPanels from being created. 
There’s only one FontPanel object for each application; you access it through either of 
the new... methods. Returns an error message. 

See also: + new, + newContent:style:backing:buttonMask:defer: 
allocFromZone: 

Disables the inherited allocFromZone method to prevent multiple FontPanels from 
being created. There’s only one FontPanel object for each application; you access it 
through either of the new... methods. Returns an error message. 

See also: + new, + newContent:style:backing:buttonMask:defer: 
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new 


+ new 

Returns a FontPanel object by invoking the 

newContent:style:backing:buttonMask:defer: method. An application has no more 
than one Font panel, so this method either returns the previously created object (if it 
exists) or creates a new one. 

See also: + new 

ne wContent: style: backing: b utt onMask: defer: 

+ newContent: (const NXRect *)contentRect 
style :(int )aStyle 
backing: (int)bufferingType 
buttonMask : (int )mask 
defer: (BOOL)/?ag 

Returns a FontPanel object. An application has no more than one Font panel, so this 
method either returns the previously created object (if it exists) or creates a new one. 
The arguments are ignored. This is the designated new... method of the FontPanel 
class. 

See also: + new 


INSTANCE METHODS 

accessoryView 

- accessoryView 

Returns the application-customized View set by set Accessory View:. 
See also: - setAccessoryView: 

isEnabled 

- (BOOL)isEnabled 

Reports whether the Font panel’s Set button is enabled. 

See also: - setEnabled: 
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orderWindow:relativeTo: 

- or der Window: (int)p/tfc<? re\ati\eTo:(mt)otherWin 

Repositions the panel in the screen list and updates the panel if it was changed while 
not visible, place can be one of: 

NX_ABOVE 

NX_BELOW 

NX_OUT 

If it’s NX_OUT, the panel is removed from the screen list and otherWin is ignored. If 
it’s NX_ABOVE or NX_BELOW, otherWin is the window number of the window that 
the Font Panel is to be placed above or below. If otherWin is 0, the panel will be placed 
above or below all other windows. 

See also: - order Window: relativeTo: (Window), - makeKeyAndOrderFront: 
(Window) 

panelConvertFont: 

- panelConvertFont:/b«rOfr/ 

Returns a Font object whose traits are the same as those of fontObj except as specified 
by the users choices in the Font Panel. If the conversion can’t be made, the method 
returns fontObj itself. The FontPanel makes the conversion by using the 
FontManager’s methods that convert fonts. A panelConvertFont: message is sent by 
the FontManager whenever it needs to convert a font as a result of user actions in the 
Font panel. 


set Accessory V iew: 

- set AccessoryView :aView 

Customizes the Font panel by adding aView above the action buttons at the bottom of 
the panel. The FontPanel is automatically resized to accommodate aViexv. 

aView should be the top View in a view hierarchy. If aView is nil, any existing 
accessory view is removed. If aView is the same as the current accessory view, this 
method does nothing. Returns the previous accessory view or nil if no accessory view 
was previously set. 

See also: - accessoryView 
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setEnabled: 

- setEnabled :(BOOL)flag 

Sets whether the Font panel’s Set button is enabled (the default state). Even when 
disabled, the Font panel allows the user to preview fonts. However, when the Font 
panel is disabled, the user can’t apply the selected font to text in the application’s main 
window. 

You can use this method to disable the user interface to the font selection system when 
its actions would be inappropriate. For example, you might disable the font selection 
system when your application has no document window. 

See also: - isEnabled 

setPanelFont: isMultiple: 

- setPanelFont ifontObj isMultiple :(BOOL)flag 

Sets the font that the FontPanel is currently manipulating. This message should only 
be sent by the FontManager. Do not send a setPanelFont:isMultiple: message 
directly. 

textDidEnd:endChar: 

- textDidEn&UextObject endChar:(unsigned shori)endChar 

A textDidEnd:endChar: message is sent to the FontPanel object when editing is 
completed in the Size field. This method updates the Size browser and the preview 
field. 

See also: - textDidGetKeys:isEmpty:, - textDidEnd:endChar: (Text) 

textDidGetKeys :isEmpty: 

- textDidGetKeys UextObject isEmpty:(BOOL)/Z<zg 

A textDidGetKeys:isEmpty: message is sent to the FontPanel object whenever the 
Size field is typed in or emptied. 

See also: - textDidEnd:endChar:, - textDidGetKeys:isEmpty: (Text) 

windowDidResize: 

- windowDidResize '.sender 

Adjusts the width of the browser columns and the accessory view in response to 
window resizing. 

See also: - windowDidResize: (Window) 
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windowWillResizeitoSize: 


- windowWillResize:sewder toSize:(NXSize *)frameSize 

Keeps the FontPanel from being sized too small to accommodate the browser columns 
and accessory view. 

See also: - windowWillResizeitoSize: (Window) 


works WhenModal 

- (BOOL)worksWhenModal 

Returns whether the FontPanel will operate while a modal panel is displayed within the 
application. By default, this method returns YES. 

See also: - worksWhenModal (Panel) 


CONSTANTS AND DEFINED TYPES 

/* Tags of View objects in the FontPanel */ 


#define NX_FPPREVIEWFIELD 128 
#define NX_FPSIZEFIELD 129 
#define NX__FPREVERTBUTTON 130 
#define NX_FPPREVIEWBUTTON 131 
#define NX_FPSETBUTTON 132 
#define NX_FPSIZETITLE 133 
#define NX FPCURRENTFIELD 134 
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Form 


INHERITS FROM Matrix : Control: View : Responder : Object 

DECLARED IN appkit/Form.h 

CLASS DESCRIPTION 

A Form is a Control that contains titled entries into which a user can type data values. 
An example: 

Name:. 

Address:. 

) 

Telephone:. 

These entries are indexed starting with zero as the topmost entry. A mouse click event 
in an entry starts text editing in that entry. A mouse click event outside the Form or a 
RETURN key event while editing an entry causes the action of the entry to be sent to 
the target of the entry if there is such an action; otherwise the action of the Form is sent 
to the target of the Form. If the user presses the Tab key, the next entry is selected. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Inherited from Control 

int 

tag; 


id 

cell; 


struct _conFlags 

conFlags; 
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Inherited from Matrix 


Declared in Form 


id 

cellList; 

id 

target; 

SEL 

action; 

id 

selectedCell; 

int 

selectedRow; 

int 

selectedCol; 

int 

numRows; 

int 

numCols; 

NXSize 

cellS ize; 

NXSize 

intercell; 

float 

backgroundGray; 

float 

cellBackgroundGray; 

id 

font; 

id 

protoCell; 

id 

cellClass; 

id 

nextText; 

id 

previousText; 

SEL 

doubleAction; 

SEL 

errorAction; 

id 

textDelegate; 

struct _mFlags 

mFlags; 

(none) 



METHOD TYPES 

Setting the Cell Class 
Initializing a Form Object 
Laying Out the Form 


Resizing the Form 


+ setCellClass: 

- initFrame: 

- addEntry: 

- addEntry:tag:target:action: 

- insertEntry:at: 

- insertEntry: at: tag: target: action: 

- removeEntryAt: 

- setlnterline: 

- calcSize 

- setEntryWidth: 

- sizeTo:: 

- sizeToFit 
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Setting Form Values 

- doubleValueAt: 

- float ValueAt: 

- int ValueAt: 

- setDoubleValue:at: 

- setFloatValue:at: 

- setlntValue:at: 

- setStringValue:at: 

- string ValueAt: 

Returning the Index 

- findlndexWithTag: 

- selectedlndex 

Modifying Text Attributes 

- setFont: 

- setTextAlignment: 

- setTextFont: 

- setTitle:at: 

- setTitleAlignment: 

- setTitleFont: 

- titleAt: 

Editing Text 

- selectTextAt: 

Modifying Graphic Attributes 

- setBezeled: 

- setBordered: 

Displaying 

- drawCellAt: 

Target and Action 

- setActiomat: 

- setTarget:at: 

Assigning a Tag 

- setTag:at: 


CLASS METHODS 

setCellClass: 

+ setCellClass iclassld 

This method initializes the subclass of Cell used in the Form. The default is FormCell. 
Use this when you subclass FormCell to modify the behavior of a Form:, by sending 
this method with the class id of your subclass as the argument. 
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INSTANCE METHODS 


addEntry: 

- addEntry: (const char *)title 

Adds a new entry with the given title at the bottom of the Form. Returns the FormCell 
used to implement the entry. Does not redraw the Form even if autodisplay is on. 

addEntry:tag:target:action: 

- addEntry: (const char *)title 

tag:(int )anlnt 
targetianObject 
action : (SE h)aSelector 

Adds a new entry with the given title at the bottom of the Form. The tag, target, and 
action of the corresponding entry are set to the given values. Returns the FormCell used 
to implement the entry. Does not redraw the Form even if autodisplay is on. 

calcSize 

- calcSize 

Invoke this method before drawing after you have modified any of the cells in the Form 
in such a way that the size of the cells or the size of the title part of the cells has changed. 
Automatically invoked before any drawing is done after a setTitle:at.\ setFont:, 
setBezeled: or some other similar method has been invoked. 

See also: - validateSize: (Matrix) 
doubleValueAt: 

- (double)double Value At : (int )index 

Returns the entry at position index, converted to a float by the C function atof() then 
cast as a double. 


drawCellAt: 

- drawCellAt:(int)/ra/ex: 

Displays the entry at the specified index in the Form. 
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findlndexWithTag: 

- (int)findIndexWithTag:(int)tf7hg 

Returns the index which has the corresponding tag, -1 otherwise. 

See also: - findCellWithTag: (Matrix) 

floatValueAt: 

- (float)float Value At: (int)mdex: 

Returns the entry at position index, converted to a float by the C function atof(). 

initFrame 

- initFrame .‘(const NXRect *)frameRect 

Initializes and returns the receiver, a new instance of Form, with default parameters in 
the given frame. The default Form has no entries. Newly created entries will have the 
following default characteristics: Titles will be right justified, text will be left justified 
with bezeled border, background colors will be white, text color black, fonts will be the 
system font 12.0, the interline spacing will be 1.0, and the action selectors will be 
NULL. This method is the designated initializer for Form; override it if you create a 
subclass of Form that performs its own initialization. 

Note that Form doesn’t override the Matrix class’s designated initializers 

initFrame: mode: cell Class: numRows: numCols : or 

initFrame:mode:prototype:numRows:numCols:. Don’t use those methods to 
initialize a new instance of Form. 

insertEntry:at: 

- insertEntry: (const char *)title at:(int )index 

Inserts a new entry with the given title at position index. Returns the FormCell used to 
implement the entry. Does not redraw the Form even if autodisplay is on. 

insertEntry: at: tag: target: action: 

- insertEntry: (const char *)title 

at:(int )index 
tag:(int )anlnt 
targetianObject 
action: (SELjaSe/ector 

Inserts a new entry with the given title at position index. The tag, target, and action of 
the corresponding entry are set to the given values. Returns the FormCell used to 
implement the entry. Does not redraw the Form even if autodisplay is on. 
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intValueAt: 


- (int)intValueAt:(int)m^A: 

Returns the entry at position index converted to an integer by the C function atoi(). 

removeEntryAt: 

- removeEntryAt :(int)index 

Removes the entry at the given index and disposes of the associated memory. Note that 
if you use Matrix’s removeRowAt:andFree: method to remove an entry, the widths of 
the titles in the entries will not be readjusted, so use this method instead. Does not 
redraw the Form even if autodisplay is on. Returns self. 

selectTextAt: 

- selectTextAt:(int)mdex 

Enters text editing on the entry at index and selects all of its contents. Do not invoke 
this function before inserting your Form in a view hierarchy with a window at the root; 
it will have no effect. Returns the id of the Cell located at index. 

selectedlndex 

- (int)selectedlndex 

Returns the index of the currently selected entry if any, -1 otherwise. The currently 
selected entry is the one being edited or, if none of the entries is being edited, then it’s 
the last edited entry. 

setAction:at: 

- setAction:(SEL )aSelector at:(int )index 

Sets the action of the FormCell associated with the entry at position index in the Form 
to aSelector. Returns self. 

setBezeled: 

- setBezeIed:(BOOL)/fag 

Sets whether to draw a bezeled frame around the text in the Form (YES is the default). 
Redraws the Form if autodisplay is on. Returns self. 

setBordered: 

- setBordered :(BOOL)/7ag 

Sets whether to draw a 1-pixel black frame around the text in the Form (rather than the 
default bezel). Redraws the Form if autodisplay is on. Returns self. 
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setDouble V alue: at: 

- setDouble Va\ue:(doub\e)aDouble at:(int )index 

Sets the text of the entry at position index to aDouble. Redraws the entry. Returns self. 

setEntry Width: 

- setEntryWidth:(NXCoord )width 

Sets the width of all the entries (including the title part). You should invoke sizeToFit 
after invoking this method. Returns self. 

setFloatValueiat: 

- setFloatValue:(float)< 2 F/o< 2 f at:(int )index 

Sets the text of the entry at position index to aFloat. Redraws the entry. Returns self. 

setFont: 

- setFont ifontObj 

Sets the font used to draw both the titles and the editable text in the Form. It’s generally 
best to keep the title font and the text font the same (or at least the same size); therefore, 
this method is preferred to setTitleFont: and setTextFont:. Redraws the Form if 
autodisplay is on. Returns self. 

setlntValueiat: 

- setlntValue: (int)anlnt at:(int )index 

Sets the text of the entry at position index to anlnt. Returns self, 
setlnterline: 

- setInterline:(NXCoord)sptfcmg 

Changes the value of the interline spacing. Does not redraw the matrix even if 
autodisplay is on. Returns self. 

setStringValue:at: 

- setStringValue: (const char *)aString at:(int )index 

Sets the text of the entry at position index to a copy of aString. The entry is redrawn. 
Returns self. 
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setTag:at: 

- setTag:(int )anlnt at:(int)index 

Sets the tag of the FormCell associated with the entry at position index in the Form to 
anlnt. Returns self. 

setTarget:at: 

- setTarg etianObject at:(int )index 

Sets the target of the FormCell associated with the entry at position index in the Form 
to anObject. 

setTextAlignment: 

- setTextAlignment:(int)ra<9de 

Sets the justification mode for the editable text in the Form, mode can be one of three 
constants: NX_LEFTALIGNED, NX_CENTERED or NX_RIGHTALIGNED. 
Redraws the Form if autodisplay is on, and returns self. 

setTextFont: 

- setTextFontifontObj 

Sets the font used to draw the editable text in the Form. Redraws the Form if 
autodisplay is on, and returns self. 

See also: - setFont: 
setTitleiat: 

- setTitle: (const char *)aString at:(int )index 
Changes the title of the entry at position index to aString. 

setTitleAlignment: 

- setTitleAlignment :(int)mode 

Sets the justification mode for titles in the Form, mode can be one of three constants: 
NXJLEFTALIGNED, NX_CENTERED or NX_RIGHTALIGNED. Redraws the 
Form if autodisplay is on, and returns self. 
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setTitleFont: 

- setTitleFont ifontObj 

Sets the font used to draw the titles in the Form. Redraws the Form if autodisplay is on 
and returns self. 

See also: - setFont: 

sizeTo:: 

- sizeTo: (NXCoord )width :(NXCoord )height 

Resizes the entry width to reflect width, then resizes the Form to width and height. 
Returns self. 

sizeToFit 

- sizeToFit 

Adjusts the width of the Form so that it s the same as the width of the entries. Adjusts 
the height of the Form so that it will just contain all of the cells. Returns self. 

See also: - setEntryWidth: 
string Value At: 

- (const char *)string Value At: (intjmdo: 

Returns a pointer to the text (contents) of the entry at position index. 

titleAt: 

- (const char *)titleAt:(int)md<?x 

Returns a pointer to the title of the entry at position index. 
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FormCell 


INHERITS FROM ActionCell: Cell: Object 

DECLARED IN appkit/FormCell.h 

CLASS DESCRIPTION 

This class is used to implement the details of the Form class. Form is a subclass of 
Matrix, and this is the cell which goes in that Matrix. The titleCell is used to draw the 
title of the FormCell. The title Width is the width of the title (in pixels). If it’s -1.0, 
then the title is autosized to the width of the titleCell. The titleEndPoint is the 
coordinate at which the title ends and the editable text begins. 

If you want to change the look of a Form, then you should subclass FormCell. When 
you do so, remember to implement both drawSelfiinView: and drawlnsiderin View:. 
The initTextCell: method is the designated initializer for FormCell; override this 
method if your subclass performs its own initialization. 

INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Cell 

char 

♦contents; 


id 

support; 


struct _cFlagsl 

cFlagsl; 


struct _cFlags2 

cFlags2; 

Inherited from ActionCell 

int 

tag; 


id 

target; 


SEL 

action; 

Declared in FormCell 

NXCoord 

titleWidth; 


id 

titleCell; 


NXCoord 

titleEndPoint; 


titleWidth The width of the title field. 

titleCell The cell used to draw the title. 

titleEndPoint The coordinate that separates the title from the 

text area. 
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METHOD TYPES 


Copying, Initializing, and Freeing a FormCell 



- copy 

- init 

- initTextCell: 

- free 

Determining the FormCell’s Size 

- calcCellSize-.inRect: 

Enabling and Disabling the FormCell 

- setEnabled: 

Modifying the Title 

- setTitle: 

- setTitleAlignment: 

- setTitleFont: 

- setTitle Width: 

- title 

- titleAlignment 

- titleFont 

- title Width 

- title Width: 

Modifying Graphic Attributes 

- isOpaque 

Displaying 

- drawlnside: in View: 

- drawSelfdnView: 

Managing the Cursor 

- resetCursorRect:inView: 

Tracking the Mouse 

- trackMouse:inRect:ofView: 

Archiving 

- read: 

- write: 


INSTANCE METHODS 

calcCellSize: inRect: 

- calcCellSize:(NXSize *)theSize inRect:(const NXRect *)aRect 

Calculates the size of the FormCell assuming it’s constrained to fit within aRect. 
Returns the size in theSize. 

copy 

-copy 

Creates and returns a copy of the receiving FormCell instance. 
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drawlnside: in V iew: 


- drawlnside: (const NXRect *)cellFrame inViewicontrolView 

Draws only the text inside the FormCell (not the bezels or the title of the FormCell). 
This is called from the Control method drawCelllnside: (which is called from Cell 
setType Value: methods). If you subclass FormCell and override drawSelf:inView: 
you MUST implement this method as well. Returns self. 

drawSelf:inView: 

- drawSelf: (const NXRect *)cellFrame in View icontrolView 

Draws the FormCell by sending drawSelf:inView: to the titleCell with the frame 
width set to the title Width (if the title Width is -1.0, then the width is calculated), and 
then sending drawSelf: inView: to super. Does not invoke [super drawSelf: in View:] 
nor does it invoke [self drawInside:inView:] (it does, however, invoke [super 
drawInside:inView:]). Returns self. 

free 

- free 

Frees the storage used by the FormCell (the titleCell) and returns nil. 


init 


- init 


Initializes and returns the receiver, a new instance of FormCell, with its contents set to 
the empty string (“”) and its title set to “Field.” 


initTextCell: 

- initTextCell: (const char *)aString 


Initializes and returns the receiver, a new instance of FormCell, with its contents set to 
the empty string (“”) and its title set to aString. This method is the designated initializer 
for FormCell. 


isOpaque 

- (BOOL)isOpaque 

Returns YES if the FormCell is opaque, NO otherwise. If the FormCell has a title, then 
it’s NOT opaque (since the title field is not opaque). 
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read: 


- read:(NXTypedStream *)stream 

Reads the FormCell from the typed stream stream. 

resetCursorRect: in View: 

- resetCursorRect: (const NXRect *)cellFrame in View icontrolView 
Sets up an appropriate cursor rectangle in controlView. 

setEnabled: 

- setEnabled :(BOOL)flag 

Enables or disables the FormCell. 

setTitle: 

- setTitle: (const char *)aString 
Sets the title of the FormCell. 

setTitleAlignment: 

- setTitleAlignment:(int)/77oJe 

Sets the alignment of the title, mode can be one of three constants: 
NX_LEFTALIGNED, NX_CENTERED, or NX_RIGHTALIGNED. 

setTitleFont: 

- setTitleFont \fontObj 

Sets the font used to draw the title of the FormCell. 

setTitle Width: 

- setTitleWidth:(NXCoord)w/<ir/z 

Sets the width of the title field. Can be “unset”by providing -1.0 as the width. 

title 

- (const char *)title 

Returns the title of the FormCell. 
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titleAlignment 

- (int)titleAlignment 

Returns the alignment of the title. The return value will match one of three constants: 
NXJJEFTALIGNED, NX_CENTERED, or NX_RIGHTALIGNED. 

titleFont 

- titleFont 

Returns the font used to draw the title of the FormCell. 

titleWidth 

- (NXCoord)titleWidth 

If the width of the title has already been set (i.e., it’s not -1.0), then that value is 
returned. Otherwise, it’s calculated (not constrained to any rectangle) and returned. 

titleWidth: 

- (NXCoord)titleWidth:(const NXSize *)aSize 

If the title width is already set (i.e., it’s not -1.0), then it’s returned. Otherwise, the 
width is calculated constrained to aSize. 

trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent*)cv<?«? 

inRect:(const NXRect *)aRect 
ofView icontrolView 

Does nothing since clicking in a FormCell causes editing to occur. 

write: 

- write:(NXTypedStream *)stream 

Writes the receiving FormCell to the typed stream stream and returns self. 
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Listener 


INHERITS FROM Object 

DECLARED IN appkit/Listener.h 

CLASS DESCRIPTION 

The Listener class, with the Speaker class, supports communication between 
applications (tasks) through Mach messaging. Mach messages are the standard way of 
performing remote procedure calls (RPCs) in the Mach operating system. The Listener 
class implements the receiving end of a remote message, and the Speaker class 
implements the sending end. 

Remote messages are sent to ports, which act something like mailboxes for the tasks 
that have the right to receive the messages delivered there. Each Listener corresponds 
to a single Mach port to which its application has receive rights. Since a port has a fixed 
size—usually there’s room for only five messages in the port queue—when the port is 
full, a new message must wait for the Listener to take an old message from the queue. 

To initiate a remote message, you send an Objective-C message to a Speaker instance. 
The Speaker method that responds to the message translates it into the proper Mach 
message protocol and dispatches it to the port of the receiving task. The Mach message 
is received by the Listener instance associated with the port. The Listener verifies that 
it understands the message, that the Speaker has sent the correct parameters for the 
message, and that all data values are well formed—for example, that character strings 
are null-terminated. The Listener translates the Mach message back into an 
Objective-C message, which it sends to itself. It’s as if an Objective-C message sent to 
a Speaker in one task is received by a Listener in another task. 


Delegation 

The Listener methods that receive remote Objective-C messages simply pass those 
messages on to a delegate. The Listener’s job is just to get the message and find another 
object to respond to it. 

The setDelegate: method assigns a delegate to the Listener. There’s no default 
delegate, but before the Application object gets its first event, it registers a Listener for 
the application and makes itself the Listener’s delegate. You can register your own 
Listener (with Application’s setAppListener: method) in start-up code, but when you 
send the Application object a run message, it will become the Listener’s delegate. 

If an object has its own delegate when it becomes the Listener’s delegate, the Listener 
looks first to its delegate’s delegate and only then to its own delegate when searching 
for an object to entrust with a remote message. This means that you can implement the 
methods that respond to remote messages in either the Application object’s delegate or 
in the Application object. (You can also implement the methods directly in a Listener 
subclass, or in another object you make the Listener’s delegate.) 
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Setting Up a Listener 

Two methods, checkin As: and usePrivatePort, allocate a port for the Listener: 

• With the checkin As: method, the Listener’s port is given a name (usually the name 
of the application) and is registered with the network name server. This makes the 
port publicly available so that other applications can find it. Applications get send 
rights to a public port through the NXPortFromName() function. 

• Alternatively, the Listener’s port can be kept private (with the usePrivatePort 
method). Send rights to the port can then be doled out only to selected applications. 

Once allocated, the port must be added (with the addPort method) to the list of those 
that the client library monitors. A procedure will automatically be called to read Mach 
messages from the port queue and begin the Listener’s process of transforming the 
Mach message back into an Objective-C message. The procedure is called between 
events, provided the priority of getting remote messages is at least as high as the priority 
of getting the next event. 

A Listener is typically set up as follows: 


myListener = [[Listener alloc] init]; 
[myListener setDelegate:someOtherObject]; 
/* 


* Sets the object responsible for handling 

* messages received. 

*/ 

[myListener checklnAs:"portname"]; 

/* or [myListener usePrivatePort] */ 
[myListener addPort]; 

/* 


* Now, between events, the client library 

* will check to see if a message has arrived 

* in the port queue. 

*/ 


[myListener free]; 

/* When we no longer need the Listener. */ 


An application may have more than one Listener and Speaker, but it must have at least 
one of each to communicate with the Workspace Manager and other applications. If 
your application doesn’t create them, a default Listener and Speaker are created for you 
at start-up before Application’s run method gets the first event. 


If a Listener is created for you, it will be checked in automatically under the name 
returned by Application’s appListenerPortName method. Normally, this is the name 
assigned to the application at compile time. The port will also be added to the list of 
those the client library monitors, so the Listener will be scheduled to receive messages 
asynchronously. 
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Remote Methods 


The Listener and Speaker classes implement a number of methods that can be used to 
send and receive remote messages. You can add other methods in Listener and Speaker 
subclasses. The msgwrap program can be used to generate subclass definitions from 
a list of method declarations. Most programmers will use msgwrap instead of 
manually subclassing the Listener class. See the man page for msgwrap for details. 

The Listener class declares the same set of remote methods as the Speaker class. 
However, applications will use some of these methods only in their Speaker versions to 
send messages and others only in their Listener versions to receive messages. For 
example, launchProgram:ok: messages are normally sent by applications to the 
Workspace Manager, which has the responsibility for launching applications, so in 
general only the Speaker version of the method will be used. On the other hand, 
unmounting:ok: messages are received by applications when the Workspace Manager 
is ready to unmount an optical disk. Since the Workspace Manager is in charge of 
mounting and unmounting disks, applications won’t send this message but will use the 
Listener version of the method to receive it. 

Some remote methods, especially those with the prefix “msg”, are designed to allow an 
application to run under program control rather than user control. By implementing 
these methods, you’ll permit a controlling application to run your application in 
conjunction with others as part of a script. 


Argument T^pes 


Remote messages take two kinds of arguments—input arguments, which pass values 
from the Speaker to the Listener, and output arguments, which are used to pass values 
back from the Listener to the Speaker. The Listener sends return information back to 
the Speaker in a separate Mach message to a port provided by the Speaker. The Speaker 
reformats this information so that it’s returned by reference in variables specified in the 
original Objective-C message. 


A method can take up to NX_MAXMSGPARAMS arguments. Arguments are 
constrained to a limited set of permissible types. Internally, the Listener and Speaker 
identify each permitted type with a unique character code. Input argument types and 
their identifying codes are listed below. Note that an array of bytes counts as a single 
argument, even though two Objective-C parameters are used to refer to it—a pointer to 
the array and an integer that counts the number of bytes in the array. A character string 
must be null-terminated. 


Category 

integer 

double 

character string 
byte array 
receive rights (port) 
send rights (port) 


Type Character Code 


(int) i 

(double) d 

(char *) c 

(char *), (int) b 

(port_t) r 

(port_t) s 
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There’s a matching output argument for each of these categories. Since output 
arguments return information by reference, they’re declared as pointers to the 
respective input types: 


Category 

integer 

double 

character string 
byte array 
receive rights (port) 
send rights (port) 


Type Character Code 

(int *) I 

(double *) D 

(char **) C 

(char **), (int *) B 

(port_t *) R 

(port_t *) S 


The validity of all input parameters is guaranteed for the duration of the remote 
message. The memory allocated for a character string or a byte array is freed 
automatically after the Listener method returns. If you want to save a string or an array, 
you must copy it. When the amount of input data is large, you can use the 
NXCopylnputDataQ function to take advantage of the out-of-line data feature of 
Mach messaging. This function is passed the index of the argument to be copied (the 
combination of a pointer and an integer for a byte array counts as a single argument) 
and returns a pointer to an area obtained through the vm_ailocate() function. This 
pointer must be freed with vm_deallocate(), rather than free(). Note that the size of 
the area allocated is rounded up to the next page boundary, and so will be at least one 
page. Consequently, it is more efficient to malloc() and copy amounts up to about half 
the page size. 


The application is responsible for deallocating all port parameters received with the 
port_deal!ocate() function when they’re no longer needed. 


Return Values 

All remote methods return an int that indicates whether or not the message was 
successfully transmitted. A return of 0 indicates success. 

The Listener methods that receive remote messages use the return value to signal 
whether they’re able to delegate a message to another object. If a method can’t entrust 
its message to the delegate (or the delegate’s delegate), it returns a value other than 0. 
If, on the other hand, it’s successful in delegating the message, it passes on the 
delegate’s return value as its own. In general, delegate methods should always return 0. 

The Listener doesn’t pass the return value back to the Speaker that initiated the remote 
message. However, if the Speaker is expecting return information from the Listener— 
that is, if the remote message has output arguments—a nonzero return causes the 
Listener to send an immediate message back to the Speaker indicating its failure to find 
a delegate for the remote message. The Speaker method then returns -1. 

Note that the return value indicates only whether the message got through; it doesn’t 
say anything about whether the action requested by the message was successfully 
carried out. To provide that information, a remote message must include an output 
argument. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in Listener 

char 

* portName; 


port_t 

listenPort; 


port_t 

signaturePort; 


id 

delegate; 


int 

timeout; 


int 

priority; 


portName The name under which the port is registered. 

listenPort The port where the Listener receives remote 

messages. 


signaturePort 


The port used to authenticate registration. 


delegate 


The object responsible for responding to remote 
messages received by the Listener. 


timeout How long, in milliseconds, that the Listener will 

wait for its return results to be placed in the port 
queue of the sending application. 

priority The priority level at which the Listener will 

receive messages. 


METHOD TYPES 

Initializing the class + initialize 

Initializing a new Listener instance - init 
Freeing a Listener - free 

Setting up a Listener - addPort 

- removePort 

- checkin As: 

- usePrivatePort 

- Checkout 

- listenPort 

- signaturePort 

- portName 

- setPriority: 

- priority 

- setTimeout: 

- timeout 
+ run 
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Standard remote methods 

- openFile:ok: 

- openTempFilerok: 

- launchProgramrok: 

- powerOffln: andS ave: 

- extendPowerOffBy.actual: 

- unhide 

- unmounting:ok: 

Handing off an icon 

- iconEnterediat: :iconWindow:iconX:iconY: 

icon Width: iconHeight:pathList: 

- iconMovedTo:: 

- iconReleasedAt::ok: 

- iconExitedAt:: 

- registerWindow:toPort: 

- unregisterWindow: 

Providing for program control 

- msgCalc: 

- msgCopyAsType:ok: 

- msgCutAsType:ok: 

- msgDirectory:ok: 

- msgFile:ok: 

- msgPaste: 

- msgPosition:posType:ok: 

- msgPrint:ok: 

- msgQuit: 

- msgSelection:length:asType:ok: 

- msgSetPosition:posType:andSelect:ok: 

- msgVersiomok: 

Getting file information 

- getFileInfoFor:app:type:ilk:ok: 

- getFileIconFor:TIFF:TIFFLength:ok: 

Receiving remote messages 

- messageReceived: 

- performRemoteMethod:paramList: 

- remoteMethodFor: 

Assigning a delegate 

- setDelegate: 

- delegate 

- setServicesDelegate: 

- servicesDelegate 

Archiving 

- read: 

- write: 
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CLASS METHODS 


initialize 
+ initialize 

Sets up a table that instances of the class use to recognize the remote messages they 
understand. The table lists the methods that can receive remote messages and specifies 
the number of parameters for each and their types. An initialize message is sent to the 
class the first time it’s used; you should never invoke this method. 


run 
+ run 

Sets up the necessary conditions for Listener objects to receive remote messages if 
they’re used in applications that don’t have an Application object and a main event 
loop. In other words, if an application doesn’t send a run message to the Application 
object, 


[NXApp run]; 


it will need to send a run message to the Listener class 


[Listener run]; 


for instances of the class to work. This method never returns, so your application will 
probably need to be dispatched by messages to its Listener instances. 


INSTANCE METHODS 

addPort 
- addPort 

Enables the Listener to receive messages by adding its port to the list of those that the 
client library monitors. The Listener will then be scheduled to receive messages 
between events. Returns self. 

See also: - removePort, DPSAddPortQ 
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checkin As: 


- (int)checklnAs: (const char *)name 

Allocates a port for the Listener, and registers that port as name with the Mach network 
name server. This method also allocates a signature port that’s used to protect the right 
to remove name from the name server. This method returns 0 if it successfully checks 
in the application with the name server, and a Mach error code if it doesn’t. The Mach 
error code is most likely to be one of those defined in the header files netname_defs.h 
and sys/kern_return.h 

See also: - usePrivatePort, - checkout 

checkout 

- (int)checkOut 

Removes the Listener’s port from the list of those registered with the network name 
server. This makes the port private. This method will always be successful and 
therefore always returns 0. 

See also: - checkin As: 

delegate 

- delegate 

Returns the Listener’s delegate. The default delegate is nil, but just before the first 
event is received, the Application object is made the delegate of the Listener registered 
as the Application object’s Listener. The delegate is expected to respond to the remote 
messages received by the Listener, although it may do this by sending messages to its 
own delegate. Here is an example of how this can work: When the Application object’s 
Listener receives an openFile:ok: message, it passes this message to its delegate, 
which is the Application object. The Application object, in turn, queries its delegate to 
see if it accepts another file, and if it does, the Application object sends its delegate a 
app:openFile:type: message. 

See also: - setDelegate:, - setAppListener: (Application) 

extendPo wer OffBy: actual: 

- (int)extendPowerOffBy:(int)re<7we.steG?Ms actual :(int *)actualMs 

Receives a remote message requesting the Workspace Manager for more time before 
logging out or turning the power off. Other applications use the Speaker version of this 
method to send the Workspace Manager extendPowerOffBy:actual: requests. 

See also: - extendPowerOffBy:actual: (Speaker), - powerOffIn:andSave:, 

- app:powerOffln:andSave: (Application delegate) 


2-248 Chapter 2: Class Specifications 



free 


- free 

Frees the Listener object and deallocates its listen port and its signature port. If the 
Listener’s port is registered with the network name server, it is unregistered. 

See also: - allocFromZone: (Object), - init 

getFileIconFor:TIFF:TIFFLength:ok: 

- (int)getFileIconFor:(char *)fullPath 

TIFF: (char 

TIFFLength:(int *)length 
ok:(int *)flag 

Receives a remote message to obtain information about an icon. The Workspace 
Manager implements a method that responds to this message. For information on how 
to use getFileIconFor:TIFF:TIFFlength:ok: messages to get information from the 
Workspace Manager, see the Speaker class. 

See also: - getFileIconFor:TIFF:TIFFLength:ok: (Speaker) 

getFileInfoFor:app:type:ilk:ok: 

- (int)getFileInfoFor:(char *)fullPath 

app:(char **)appName 
type:(char **)aType 
ilk:(int *)anllk 
ok:(int *)flag 

Receives a remote message to obtain information about a file. The Workspace Manager 
implements a method that can respond to this message. For information on how to use 
getFileInfoFor:app:type:ilk:ok: messages to get information from the Workspace 
Manager, see the Speaker class. 

See also: - getFileInfoFor:app:type:ilk:ok: (Speaker) 
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iconEntered: at:: icon Window: iconX: icon Y: icon Width: iconHeight: path List: 

- (int)iconEntered : (ini)windowNum 
at: (double)* 

: (double) y 

iconWindow:(int)iconWmdowNum 
iconX:(doubl z)iconX 
iconY: (&ovftAz)icoriY 
iconWidth : (double)iconWidth 
iconHeight: (doubl e)iconHeight 
path List: (const char *)pathList 

Receives a remote message from the Workspace Manager that the user has dragged an 
icon into the windowNum window. This message is received when the icon first enters 
the window, but only if windowNum was previously registered through a 
registerWindow:toPort: message to the Workspace Manager: 

unsigned int windowNum; 
id speaker = [NXApp appSpeaker]; 

NXConvertWinNumToGlobal([myWindow windowNum], SwindowNum); 

[speaker setSendPort:NXPortFromName(NX_WORKSPACEREQUEST, NULL)]; 
[speaker registerWindow:windowNum toPort:[myListener listenPort]]; 


windowNum is the global window number of the window the icon entered. (The global 
window number is the one assigned by the Window Server, not the user object 
maintained within an application.) 

x and y specify the cursor’s location in screen coordinates. 

iconWindowNum is the global window number of the off-screen window where the icon 
image is cached. The icon can be composited from that window to your own. The four 
arguments iconX, iconY, iconWidth, and iconHeight locate the rectangle occupied by 
the icon in iconWindow’s base coordinates. 

pathList is the null-terminated pathname of the file represented by the icon. If the icon 
represents a number of files, pathList will contain a list of tab-separated paths. 

You will probably want to save a copy of the file icon and/or the path list so you can use 
them in your iconMovedTo:: and iconReIeasedAt::ok: methods. The following 
implementation of this method saves both: 

char *iconPathList = NULL; 

NXSize size = {48.0, 48.0}; 

myFilelcon = [[NXImage alloc] initSize:&size]; 

- (int)iconEntered:(int)windowNum at:(double)winX :(double)winY 
iconWindow:(int)iconWindowNum iconX:(double)x iconY:(double)y 
iconWidth:(double)w iconHeight:(double)h 
pathList:(char *)pathList 
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{ 

/* lock focus on the image so we can use the pswrap function */ 

/* to copy the icon from the icon's window */ 

[myFilelcon lockFocus]; 

copylconPicture(iconWindowNum, (float)x, (float)y, 

(float)w, (float)h); 

[myFilelcon unlockFocus]; 

/* The icon now has a copy of the picture. Let's make */ 

/* a copy of the path list */ 

if (iconPathList) NX_FREE(iconPathList); 

/* allocate space for the path list and copy the string */ 
iconPathList = NXCopyStringBuffer(pathList); 

/* Don't forget to free your copy of the path list in your */ 

/* iconReleasedAt::ok: and iconExitedAt:: methods. You will */ 

/* also need to set iconPathList to NULL */ 
return 0; 

} 

In order to copy the icon to your image, you’ll need a copylconPictureO function. Put 
the following pswrap in a file with an extension of .psw: 


defineps copylconPicture(int win; float x; float y; float w; float h) 
x y w h gsave win windowdeviceround gstate grestore 0 0 
Copy composite 
endps 


See also: - registerWindow:toPort: (Speaker), - iconMovedTo::, 

- iconReleasedAt: :ok:, - dragFile:fromRect:slideBack:event: (View) 

iconExitedAt:: 

- (int)iconExitedAt:(double)x :(double)y 

Receives a remote message from the Workspace Manager that the user has dragged an 
icon out of a registered window. An iconExitedAt:: message will be received only 
after the application has been notified that the icon entered the window. The two 
arguments, x and y, specify the cursor’s location in screen coordinates when the icon 
exited the window. 

See also: 

- iconEntered:at::iconWindow:iconX:iconY:iconWidth:iconHeight:pathList: 
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iconMovedTo:: 


- (int)iconMovedTo: (double)^ :(double)y 

Receives a remote message from the Workspace Manager that the user has dragged an 
icon to the cursor location (x, y) in screen coordinates. You will probably want to use 
Window’s convertScreenToBase: method to convert these points to window 
coordinates, and View’s convertPoint: from View: method to then convert them to the 
coordinate system of a particular View. iconMovedTo:: messages are repeatedly 
received while the icon is being dragged within a registered window. They’re received 
only after the application has been notified that the icon entered the window and before 
it has been notified that the icon exited the window. 

See also: 

- iconEntered:at::iconWindow:iconX:iconY:iconWidth:iconHeight:pathList:, 

- convertScreenToBase: (Window), - convertPoint:fromView: (View), 

- iconReleasedAt::ok: 

iconReleasedAt::ok: 

- (int)iconReleasedAt:(double)x 

:(double)y 
ok:(int *)flag 

Receives a remote message from the Workspace Manager when the user releases an 
icon over a registered window. The Workspace Manager sends an 
iconReleasedAt: :ok: message only after notifying the application that the icon entered 
the window. Your iconEntered:at:... method should save the icon’s image and 
pathname if you need them for this method. 

The first two arguments, x and y, specify the location of the cursor in screen coordinates 
when the user let go of the mouse button to stop dragging the icon. 

The iconReleasedAt::ok: method you implement should set the integer referred to by 
flag to 1 if you want the Workspace Manager to hide the icon window the user was 
dragging, or to 0 if you want the Workspace Manager to animate the icon back to its 
source window (indicating to the user that your window didn’t accept it). 

See also: 

- iconEntered:at::iconWindow:iconX:iconY:iconWidth:iconHeight:pathList:, 

- iconMovedTo:: 
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Initializes the Listener which must be a newly allocated Listener instance. The new 
instance has no port name, its priority is set to NX_BASETHRESHOLD, its timeout is 
initialized to 30,000 milliseconds, its listen port and signature port are both 
PORT_NULL, and it has no delegate. Returns self. 

See also: + alloc (Object), + allocFromZone: (Object), + new (Object), 

- setPriority:, - setTimeout:, - setDelegate:, - checkin As: 

launchProgranr.ok: 

- (int)launchProgram: (const char *)name ok:(int *)flag 

Receives requests to launch an application. The Workspace Manager is the application 
that properly responds to these requests. See the Speaker class for information on how 
to send launchProgram:ok: messages to the Workspace Manager. 

See also: - launchProgramrok: (Speaker) 

listenPort 

- (port_t)listenPort 

Returns the port at which the Listener receives remote messages. This port is never set 
directly, but is allocated by either checklnAs: or usePrivatePort. It’s deallocated by 
the free method. The Listener caches this port as its listenPort instance variable. 

See also: - checklnAs:, - usePrivatePort, - free 

messageRecei ved: 

- messageReceived:(NXMessage *)msg 

Begins the process of translating a Mach message received at the Listener’s port into an 
Objective-C message. This method verifies that the Mach message is well formed, that 
it corresponds to an Objective-C method understood by the Listener, and that the 
method’s arguments agree in number and type with the fields of the Mach message. 

messageReceived: messages are initiated whenever a Mach message is to be read from 
the Listener’s port; you shouldn’t initiate them in the code you write. Returns self. 

See also: - performRemoteMethod:paramList: 
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msgCalc: 

- (int)msgCalc:(int *)flag 

Receives a remote message to perform any calculations that are necessary to bring the 
current window up to date. The method you implement to respond to this message 
should set the integer specified by flag to YES if the calculations will be performed, and 
to NO if they won’t. 

msgCopy AsTy pe: ok: 

- (int)msgCopyAsType: (const char *)aType ok:(int *)flag 

Receives a remote message requesting the application to copy the current selection to 
the pasteboard as aType data. aType should be one of the standard pasteboard types 
defined in appkit/Pasteboard.h. The method you implement to respond to this request 
should set the integer referred to by flag to YES if the selection is copied, and to NO if 
it isn’t. 

msgCutAsTyperok: 

- (int)msgCutAsType: (const char *)aType ok:(int *)flag 

Receives a remote message requesting the application to delete the current selection 
and place it in the pasteboard as aType data. aType should be one of the standard 
pasteboard types defined in appkit/Pasteboard.h. The method you implement to 
respond to this request should set the integer referred to by flag to YES if the requested 
action is carried out, and to NO if it isn’t. 

msgDirectory: ok: 

- (int) msgDirectory: (char *const *)fullPath ok:(int *)flag 

Receives a remote message asking for the current directory. The method you 
implement to respond to this message should place a pointer to the full path of its 
current directory in the variable specified by fullPath. The integer specified by flag 
should be set to YES if the directory will be provided, and to NO if it won’t. 

The current directory is application-specific, but is probably best described as the 
directory the application would show in its Open panel were the user to bring it up. 
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msgFile:ok: 

- (int)msgFile:(char *const *)fullPath ok:(int *)flag 

Receives a remote message requesting the application to provide the full pathname of 
its current document. The current document is the file displayed in the main window. 

The method you implement to respond to this request should set the pointer referred to 
by fullPath so that it points to a string containing the full pathname of the current 
document. The integer specified by flag should be set to YES if the pathname is 
provided, and to NO if it isn’t. 


msgPaste: 

- (int)msgPaste:(int *)flag 

Receives a remote message requesting the application to replace the current selection 
with the contents of the pasteboard, just as if the user had chosen the Paste command 
from the Edit menu. The method you implement to respond to this message should set 
the integer referred to by flag to YES if the request is carried out, and to NO if it isn’t. 


msgPosition: posTy pe: ok: 

- (int)msgPosition:(char *const *)aString 
posiype:(int *)anlnt 
ok:(int *)flag 

Receives a remote message requesting a description of the current selection. 

The method you implement to respond to this request should describe the selection in 
a character string and set the pointer referred to by aString so that it points the 
description. The integer referred to by anlnt should be set to one of the following 
constants to indicate how the current selection is described: 


NX_TEXTPOSTYPE 

NXJREGEXPRPOSTYPE 

NX_LINENUMPOSTYPE 

NX_CHARNUMPOSTYPE 


As a character string to search for 

As a regular expression to search for 

As a colon-separated range of line numbers, for 
example “10:12” 

As a colon-separated range of character positions, 
for example “21:33” 


NX_APPPOSTYPE As an application-specific description 


The integer referred to by flag should be set to YES if the requested information is 
provided in the other two output arguments, and to NO if it isn’t. 
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msgPrint:ok: 

- (int)msgPrint:(const char *)fullPath ok:(int *)flag 

Receives a remote message requesting the application to print the document whose path 
is fullPath. The method you implement to respond to this request should set the integer 
referred to by flag to YES if the document is printed, and to NO if it isn’t. The 
document file should be closed after it’s printed. 

msgQuit: 

- (int)msgQuit:(int *)flag 

Receives a remote message for the application to quit. The method you implement to 
respond to this message should set the integer specified by flag to YES if the application 
will quit, and to NO if it won’t. 

msgSelection:length:asType:ok: 

- (int)msgSelection:(char *const *)bytes 

length:(int *)numBytes 
aslope: (const char *)aType 
ok:(int *)flag 

Receives a remote message asking the application for its current selection as aType 
data. aType will be one of the following standard data types for the pasteboard (or an 
application-specific type): 

NXAsciiPboardType 

NXPostScriptPboardiype 

NXTIFFPboardType 

NXRTFPboardType 

NXSoundPboardType 

NXFilenamePboardType 

NXTabularTextPboardType 

The method you implement to respond to this request should set the pointer referred to 
by bytes so that it points to the selection and also place the number of bytes in the 
selection in the integer referred to by numBytes. The integer referred to by flag should 
be set to YES if the selection is provided, and to NO if it’s not. 

msgSetPosition:posType:andSelect:ok: 

- (int)msgSetPosition: (const char *)aString 

posType:(int )anlnt 
&n&Se\ect:(mt)selectFlag 
ok:(int *)flag 

Receives a remote message requesting the application to scroll the current document 
(the one displayed in the main window) so that the portion described by aString is 
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visible. aString should be interpreted according to the anlnt constant, which will be 
one of the following: 


NX_TEXTPOSTYPE 

NX_REGEXPRPOSTYPE 

NX_LINENUMPOSTYPE 


aString is a character string to search for. 

aString is a regular expression to search for. 

aString is a colon-separated range of line 
numbers, for example “10:12”. 


NX_CHARNUMPOSTYPE aString is a colon-separated range of character 

positions, for example “21:33”. 

NX_APPPOSTYPE aString is an application-specific description of a 

portion of the document. 


The msgSetPositionrposTyperandSelectrok: method you implement should set the 
integer referred to by flag to YES if the document is scrolled, and to NO if it isn’t. If 
selectFlag is anything other than 0, the portion of the document described by aString 
should also be selected. 


msgVersion:ok: 

- (int)msgVersion:(char *const *)aString ok:(int *)flag 

Receives a remote message requesting the current version of the application. The 
method you implement to respond to this request should set the pointer referred to by 
aString so that it points to a string containing current version information for your 
application. The integer specified by flag should be set to YES if version information 
is provided, and to NO if it’s not. 

openFile:ok: 

- (int)openFile: (const char *)fullPath ok:(int *)flag 

Receives a remote message asking the application to open a file. The file is identified 
by an absolute pathname, fullPath. 

The Application object, NXApp, has an openFilerok: method that can respond to this 
message. Much of the task of opening and displaying the file is left to the application, 
however. This can be done by implementing an appOpenFilertype: method, either for 
NXApp’s delegate or in an Application subclass, rather than a version of openFilerok:. 

If you implement your own version of openFilerok:, it should set the output argument 
specified by flag to YES if the application will open the file, and to NO if it won’t. It 
should return 0 to indicate that the remote message was handled. 

See also: - appropenFilertype: (Application delegate), - openFilerok: (Application) 
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openTempFiIe:ok: 

- (int)openTempFile: (const char *)fullPath ok:(int *)flag 

Receives a remote message asking the application to open a temporary file. The 
temporary file is identified by an absolute pathname, fullPath. The application that 
receives this message should delete the file when it’s no longer needed. 

The Application class implements a openTempFileiok: method that can respond to 
this message. 

See also: - appiopenTempFileitype: (Application delegate), 

- openTempFile:ok: (Application), - openFileiok: (Application) 

performRemoteMethodiparamList: 

- (int)performRemoteMethod:(NXRemoteMethod *)method 

paramList:(NXParam Value *)params 

Matches the data received in the Mach message with the corresponding Objective-C 
method and initiates the Objective-C message to self. The Listener method that 
receives the message will then try to delegate it to another object, method is a pointer 
to the method structure returned by remoteMethodFor: and params is a pointer to the 
list of arguments. 

The msgwrap program automatically generates a 

performRemoteMethodiparamList: method for a Listener subclass. Each Listener 
subclass must define its own version of the method. 

performRemoteMethodiparamList: messages are initiated when the Listener reads 
a Mach message from its port queue. 

See also: msgwrap (in the Unix manual) 

portName 

- (const char *)portName 

Returns the name under which the Listener’s port (the port returned by the listenPort 
method) is registered with the network name server. 

See also: - checklnAsi, - listenPort, - appListenerPortName (Application) 
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powerOffln:andSave: 

- (int)powerOffTn:(int)ms andSave:(int )aFlag 

Receives a remote message from the Workspace Manager that the machine will be 
powered down, or the user will be logged out, in ms milliseconds. The second 
argument, aFlag, should be ignored. If ms is insufficient time, the application can ask 
for additional time by sending an extendPowerOffBy.‘actual: to the Workspace 
Manager. 

The Application class implements a powerOffIn:andSave: method that can respond 
to this message. It raises an exception that’s caught by the main event loop, which then 
notifies the Application object’s delegate with an appPowerOfflmandSave: message. 

See also: - app:powerOffIn:andSave: (Application delegate), 

- powerOfflnrandSave: (Application) 

priority 

- (int)priority 

Returns the priority level for receiving remote messages. This value is cached as the 
Listener’s priority instance variable. 

See also: - setPriority: 
read: 

- read:(NXTypedStream *)stream 

Reads the Listener from the typed stream stream. 

See also: - write: 

registerWindow:toPort: 

- (int)registerWindow: (ini)windowNum toPort:(port_t)«Pe>rr 

Receives a remote message registering windowNum to receive icons the user drags into 
the window. The Workspace Manager implements a method that responds to this 
message. Other applications will use the Speaker version of the method to send the 
Workspace Manager registerWindow:toPort: messages. 

See also: - registerWindow.toPort: (Speaker), - iconEntered:at:... 
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remoteMethodFor: 


- (NXRemoteMethod *)remoteMethodFor:(SEL)<2iS£/ector 

Looks up aSelector in the table of remote messages the Listener understands and 
returns a pointer to the table entry. A NULL pointer is returned if aSelector isn’t in the 
table. 

Each Listener subclass must define its own version of this method and send a message 
to super to perform the Listener version. The msgwrap program produces subclass 
method definitions automatically. The version of the method produced by msgwrap 
uses the NXRemoteMethodFromSeI() function to do the look up. 

remoteMethodFor: messages are initiated automatically when the Listener reads a 
Mach message from its port queue. 

See also: - performRemoteMethodrparamList:, msgwrap (in the Unix manual) 

removePort 

- removePort 

Removes the Listener’s port from the list of those that the client library monitors. 
Remote messages sent to the port will pile up in the port queue until they are explicitly 
read; they won’t be read automatically between events. 

See also: - addPort 

servicesDelegate 

- servicesDelegate 

Returns the Listener’s services delegate, the object that will respond to remote 
messages sent from the Services menus of other applications. The services delegate 
should contain the methods that a service providing application uses to provide services 
to other applications. 

See also: - setServicesDelegate: 

setDelegate: 

- setDelega teianObject 

Sets the Listener’s delegate to anObject. The delegate is expected to respond to the 
remote messages received by the Listener. However, if anObject has a delegate of its 
own at the time the setDelegate: message is sent, the Listener will first check to see if 
that object can handle a remote message before checking anObject. In other words, the 
Listener recognizes a chain of delegation. 
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The delegate assigned by this method will be overridden if the Listener is registered as 
the Application object’s appListener and the assignment is made before the 
Application object is sent a run message. Before getting the first event, the run method 
makes the Application object the appListener ’s delegate. 

See also: - delegate, - set AppListener: (Application) 

setPriority: 

- setPriority :(int )level 

Sets the priority for receiving remote messages to level. Whenever the application is 
ready to get another event, the priority level is compared to the threshold at which the 
application is asking for the next event. For the Listener to be able to receive remote 
messages from its port queue, the priority level must be at least equal to the event 
threshold. 

Priority values can range from 0 through 30, but three standard values are generally 
used: 

NX_MODALRESPTHRESHOLD 10 

NX_RUNMODALTHRESHOLD 5 

NX_BASETHRESHOLD 1 

These constants are defined in the appkit/Application.h header file. 

• At a priority equal to NX_BASETHRESHOLD, the Listener will be able to receive 
messages whenever the application asks for an event in the main event loop, but not 
during a modal loop associated with an attention panel nor during a modal loop 
associated with a control such as a button or slider. 

• At a priority equal to NX_RUNMODALTHRESHOLD, the Listener will receive 
remote messages in the main event loop and in the event loop for an attention panel, 
but not during a control event loop. 

• At a priority equal to NX_MODALRESPTHRESHOLD, remote messages are 
received even during a control event loop. 

The default priority level is NX_BASETHRESHOLD. 

A new priority takes effect when the Listener receives an addPort message. To change 
the default, you must either set the Listener’s priority before sending it an addPort 
message, or you must send it a removePort message then another addPort message. 

See also: - priority, - addPort 
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setSer vicesDelegate: 

- setServicesDelegate:<2«0Z?y'ecf 

Registers anObject as the object within a service provider that will respond to remote 
messages. This method returns self. As an example, consider an application called 
Thinker that provides a ThinkAboutlt service that ponders the meaning of Ascii text it 
receives on the pasteboard. Thinker would need to have something like the following 
in the_services section of its_ICON segment in its Mach-O file: 

Message: thinkMethod 
Port: Thinker 

Send Type: NXAsciiPboardType 
Menu Item: ThinkAboutlt 


To get this information in your Mach-0 file you could put the above text in a file called 
services.txt and then include the following line in your Makefile.preamble file: 

LDFLAGS = -segcreate _ICON _services services.txt 

Alternatively, if the services the application can provide are not known at compile time, 
the application can build a services file at run time; see NXUpdateDynamicServices(). 

Then, in order to provide the ThinkAboutlt service you must implement a 
thinkMethod:userData:error: method in an object which is the services delegate of 
a Listener which is listening on the Thinker port. (If the application is named 
“Thinker”, then by default NXApp’s Listener listens on this port.) Here is an example 
method that could be used to provide the ThinkAboutlt service: 


- thinkMethod:(id)pb 

userData:(const char *)userData 
error:(char **)msg 

{ 

char *data; 
int length; 

char *const *s; /* We use s to go through types. */ 

char *const *types = [pb types]; 

for (s = types; *s; s++) 

if (!strcmp(*s, NXAsciiPboardType)) break; 
if (*s && [pb readType:NXAsciiPboardType 

data:&data length:&length]) 

{ 

/* doSomething is your own method... */ 

[self doSomething:data :length]; 

/* free the memory allocated by readType:... */ 
vm_deallocate(task_self(), data, length); 

} 

/* now make msg point to an error string if */ 

/* anything went wrong, and return... */ 
return self; 

} 
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See also: - servicesDelegate, 

- registerServicesMenuSendTypesiandReturnl^pes: (Application), 

- validRequestorForSendType:andReturnType: (Responder) 


setTimeout: 

- setTimeout: (int)ms 

Sets, to ms milliseconds, how long the Listener will persist in attempting to send a 
return message back to the Speaker that initiated the remote message. If ms is 0, there 
will be no time limit. The default is 30,000 milliseconds. Returns self. 

See also: - timeout 

signaturePort 

- (port_t)signaturePort 

Returns the port that’s used to authenticate the Listener’s port to the network name 
server. This port is never set directly, but is allocated by checkin As: and deallocated 
by free. The Listener caches this port as its signaturePort instance variable. 

See also: - checklnAs:, - free, netname_check_in(), netname_check_out() 

timeout 

- (int)timeout 

Returns the number of milliseconds the Listener will wait for a return message to the 
Speaker to be successfully placed in the port designated by the Speaker. This value is 
cached by the Listener as its timeout instance variable. If it’s 0, there’s no time limit. 

See also: - setTimeout: 


unhide 

- (int)unhide 

Receives a remote message asking the application to unhide its windows and become 
the active application. When the user double-clicks a freestanding or docked icon for 
a running application, the Workspace Manager sends the application an unhide 
message. The Application object has an unhide method that can respond appropriately 
to this message. The Application object notifies its delegate with an appDidUnhide 
message, if its delegate can respond. Returns the delegate’s return value if the 
Listener’s delegate responds to this message, otherwise returns -1. 

See also: - unhide (Application) 
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unmounting: ok: 

- (int)unmounting: (const char *)fullPath ok:(int *)flag 

Receives a remote message from the Workspace Manager that a disk is about to be 
unmounted. fullPath is the full pathname of a directory on the disk that will be 
unmounted. 

The Application class implements an unmounting:ok: method that responds to this 
message. Application’s method first tries to assign responsibility for the message to its 
delegate by sending the delegate an appUnmounting: message. Failing that, it tries to 
change the current working directory so that it’s not on the disk. 

If you implement your own version of unmountingrok:, it should set the integer 
specified by flag to YES if it’s OK for the Workspace Manager to unmount the disk, 
and to NO if it’s not. Most applications will implement appUnmounting: instead of 
unmounting:ok:. Returns the delegate’s return value if the Listener’s delegate 
responds to this message, otherwise returns -1. 

See also: - unmounting:ok: (Application) 

unregisterWindow: 

- (int)unregisterWindow:(int)wm<iowAww 

Receives a remote message to cancel the registration of windowNum. The Workspace 
Manager implements a method that responds to this message. Other applications will 
send the Workspace Manager unregisterWindow: messages when they no longer want 
to be notified of icons dragged into the window. See the Speaker class for information 
on sending these messages. 

See also: - unregisterWindow: (Speaker), - registerWindow:toPort: (Speaker), 

- iconEntered:at:... 

usePrivatePort 

- (int)usePrivatePort 

Allocates a listening port for the Listener, but doesn’t register it publicly. Other tasks 
can send messages to this Listener only if they are explicitly given the address of the 
port in a message; the port is not available through the Network Name Server. This 
method is an alternative to checklnAs:. It returns 0 on success and a Mach error code 
if it can’t allocate the port. The error code will be one of those defined in the 
kernjreturn.h header file in /usr/include/sys. 

See also: - checklnAs: 
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write: 

- write :(NXTypedStream *)stream 
Writes the Listener to the typed stream stream. 
See also: - read: 


CONSTANTS AND DEFINED TYPES 

/* Port for sending messages to the Workspace Manager */ 

#define NX_WORKSPACEREQUEST NXWorkspaceName 

/* Port for acknowledging launch by Workspace Manager */ 
#define NX__WORKSPACEREPLY NXWorkspaceReplyName 

/* Reserved message numbers */ 
tdefine NX_SELECTORPMSG 35555 

#define NX_SELECTORFMSG 35556 

#define NX_RESPONSEMSG 35557 

#define NX_ACKNOWLEDGE 35558 

/*• RPC return result error returns. */ 

#define NX_INCORRECTMESSAGE -20000 

/* Maximum number of remote method parameters allowed */ 

#define NX_MAXMSGPARAMS 20 

tdefine NX_MAXMESSAGE (2048-sizeof(msg_header_t)-\ 

sizeof(msg_type_t)-sizeof(int)-\ 
sizeof(msg_type_t)-8) 

/* A message sent via Mach */ 
typedef struct _NXMessage { 
msg_header_t header; 
msg_type_t sequenceType; 
int sequence; 
msg_type__t actionType; 
char action[NX_MAXMESSAGE]; 

} NXMessage; 

/* A message received via Mach */ 
typedef struct _NXResponse { 
msg_header_t header; 
msg_type_t sequenceType; 
int sequence; 

} NXResponse; 


/* every message has one */ 
/* sequence number type */ 
/* sequence number */ 


/* every message has one */ 
/* sequence number type */ 

/* sequence number */ 

/* selector string */ 
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/* For acknowledging a message via 
typedef struct _NXAcknowledge { 
msg_header_t header; 
msg_type_t sequenceType; 
int sequence; 
msg_type_t errorType; 
int error; 

} NXAcknowledge; 

/* defines method understood by 
typedef struct _NXRemoteMethod 
SEL key; 
char *types; 

} NXRemoteMethod; 


Mach */ 

/* every message has one */ 

/* sequence number type */ 

/* sequence number */ 

/* error number type */ 

/* error number, 0 is ok */ 

Listener */ 

/* Objective-C selector */ 

/* defines types of parameters */ 


/* used to pass parameters to method */ 
typedef union { 
int ival; 
double dval; 
port_t pval; 
struct _bval { 
char *p; 
int len; 

} bval; 

} NXParamValue; 

/* 

* permissible values for the second argument of 

* msgSetPosition:posType:andSelect:ok: and msgPostion:posType:ok: 

*/ 

tdefine NXJTEXTPOSTYPE 0 
#define NX_REGEXPRPOSTYPE 1 
#define NX_LINENUMPOSTYPE 2 
tdefine NX_CHARNUMPOSTYPE 3 
tdefine NX APPPOSTYPE 4 
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INHERITS FROM 


Control: View : Responder: Object 


DECLARED IN appkit/Matrix.h 

CLASS DESCRIPTION 

The Matrix class allows creation of matrices of Cells of the same or of different types. 
The main restriction is that all Cells must have the same size. You can add rows and 
columns to a Matrix by using addRow, insertRowAt:, addCol, or insertColAt:. Cells 
created by the Matrix to fill its rows and columns will be instances of the Cell subclass 
stored in the cellClass instance variable or copies of the prototype Cell stored in the 
protoCell instance variable. 

There are four modes of operation for a Matrix: 

NX_TRACKMODE is the most basic mode of operation. All that happens in this mode 
is that the Cells are asked to track the mouse via trackMouse:inRect:ofView: 
whenever the mouse is inside their bounds. No highlighting is performed. An example 
of this mode might be a “graphic equalizer” Matrix of Sliders. Moving the mouse 
around would cause the sliders to move under the mouse. 

NX_HIGHLIGHTMODE is a modification of TRACKMODE. In this mode, a Cell is 
highlighted before it is asked to track the mouse, then unhighlighted when it is done 
tracking. Useful for multiple unconnected Cells which use highlighting to inform the 
user that they are being tracked (like buttons). 

NX_RADIOMODE is used when you want no more than one Cell to be selected at a 
time. Used in conjunction with allowEmptySel:NO, it can be used to create a set of 
buttons of which one and only one is selected. Any time a Cell is selected, that Cell’s 
action (if any) is sent to its target (or the Matrix’s target if the Cell has none). The 
canonical example of this mode is a set of radio buttons. 

NXJLISTMODE allows multiple Cells to be highlighted. The Cell is not given the 
opportunity to track the mouse; it is only highlighted. This can be used to select a range 
of text values, for example. The method sendAction:to:forAHCells:NO can be used 
to iterate through the highlighted Cells and perform various functions on them. 
Highlighting can be done in many ways including dragging to select, using the shift key 
to make disjoint selections, and using the alternate key to extend selections. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Inherited from Control 

int 

tag; 


id 

cell; 


struct _conFlags 

conFlags; 

Declared in Matrix 

id 

cellList; 


id 

target; 


SEL 

action; 


id 

selectedCell; 


int 

selectedRow; 


int 

selectedCol; 


int 

numRows; 


int 

numCols; 


NXSize 

cellSize; 


NXSize 

intercell; 


float 

backgroundGray; 


float 

cellB ackgroundGray; 


id 

font; 


id 

protoCell; 


id 

cellClass; 


id 

nextText; 


id 

previousText; 


SEL 

doubleAction; 


SEL 

errorAction; 


id 

struct _mFlags { 

textDelegate; 


unsigned int 

highlightMode:l; 


unsigned int 

radioMode:l; 


unsigned int 

listMode:l; 


unsigned int 

allowEmptySel: 1; 


unsigned int 

autoscroll: 1; 


unsigned int 

reaction: 1; 


} 

mFlags; 

cellList 

The List of Cells. 


target 

Target of the Matrix. 
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action 

Action of the Matrix. 

selectedCell 

The currently selected Cell. 

selectedRow 

The row number of selectedCell. 

selectedCol 

The column number of selectedCell. 

numRows 

Number of rows. 

numCols 

Number of columns. 

cellSize 

Width & height of the Cells. 

intercell 

Vertical and horizontal spacing between Cells. 

backgroundGray 

Background gray. 

cellB ackgroundGray 

Cells background gray. 

font 

Font of Cells. 

protoCell 

Prototypical Cell. 

cellClass 

Factory for new Cells. 

nextText 

Object to select when Tab key is pressed. 

previousText 

Object to select when Shift-Tab is pressed. 

doubleAction 

Action sent on double click. 

errorAction 

Action to apply for edit errors. 

textDelegate 

Object to which textDidEndrendChar:, etc. is 
forwarded. 

mFlags .highlightMode 

NX_HIGHLIGHTMODE. 

mFlags.radioMode 

NXJRADIOMODE. 

mFlags.listMode 

NX_LISTMODE. 

mFlags. allowEmpty Sel 

Whether no selection is allowed in 
NX_RADIOMODE. 

mFlags. autoscroll 

Autoscroll when in a Scroll View. 

mFlags.reaction 

sendAction caused the Cell to change. 
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METHOD TYPES 


Initializing the Matrix Class Object + initialize 

+ setCellClass: 

Initializing and Freeing a Matrix - initFrame: 

- initFrame:mode:cellClass:numRows: 

numCols: 

- initFrame:mode:prototype:numRows: 

numCols: 

- free 

Creating a new Cell - makeCellAt:: 

- prototype 

- setCellClass: 

- setPrototype: 

Laying out the Matrix - addCol 

- addRow 

- cellCount 

- getCellFrame:at:: 

- getCellSize: 

- getlntercell: 

- getNumRows:numCols: 

- getRow:andCol:forPoint: 

- getRow:andCol:ofCell: 

- inserted At: 

- insertRowAt: 

- removeColAt:andFree: 

- removeRowAt:andFree: 

- renewRows:cols: 

- setCellSize: 

- setlntercell: 

Modifying the Matrix - putCelhat:: 

- setMode: 

- setPreviousText: 

Modifying the Cells - sendAction:to:forAllCells: 

- setEnabled: 

- setFont: 

- setIcon:at:: 

- setState:at:: 

- setTarget:at:: 

- setTitle:at:: 
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Editing Text 


Selecting and Identifying Cells 


Modifying Graphic Attributes 


Resizing the Matrix and Cells 


Scrolling 


- select All: 

- selectText: 

- selectTextAt:: 

- setNextText: 

- setTextDelegate: 

- textDidGetKey s: i sEmpty : 

- textDelegate 

- textDidChange: 

- textDidEndrendChar: 

- textWillChange: 

- textWillEnd: 

- allowEmptySel: 

- cell At:: 

- cellList 

- clearSelectedCell 

- findCellWithTag: 

- selectCell: 

- selectCellAt:: 

- selectCellWithTag: 

- selectedCell 

- selectedCol 

- selectedRow 

- backgroundColor 

- backgroundGray 

- cellBackgroundColor 

- cellBackgroundGray 

- font 

- isBackgroundTransparent 

- isCellBackgroundTransparent 

- setBackgroundColor: 

- setBackgroundGray: 

- setBackgroundTransparent: 

- setCellBackgroundColor: 

- setCellBackgroundGray: 

- setCellBackgroundTransparent: 

- doesAutosizeCells 

- calcSize 

- setAutosizeCells: 

- sizeTo:: 

- sizeToCells 

- sizeToFit 

- validateSize: 

- scrollCellToVisible:: 

- set Autoscroll: 

- setScrollable: 
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Displaying 


Target and Action 


Assigning a Tag 


- display 

- drawCell: 

- drawCellAt:: 

- drawCelllnside: 

- drawSelf:: 

- highlightCellAt: :lit: 

- action 

- doubleAction 

- errorAction 

- sendAction 

- sendAction:to: 

- sendDoubleAction 

- set Action: 

- setAction:at:: 

- setDoubleAction: 

- setErrorAction: 

- setReaction: 

- setTarget: 

- target 

- setTagrat:: 

- setTag:target:action:at:: 


Handling Event and Action Messages 


acceptsFirstMouse 

mouseDown: 

mouseDownFlags 

performKeyEquivalent: 


Managing the Cursor 
Archiving 


- resetCursorRects 

- read: 

- write: 


CLASS METHODS 

initialize 
+ initialize 

Sets the current version of the Matrix class. 
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setCellClass: 


+ setCellClass ifactoryld 

This method initializes the subclass of Cell used by the Matrix class when the 
initFrame: method is used to initialize a Matrix. You rarely need to invoke this method 
since you usually set the cellClass or a prototype Cell by invoking the methods 
initFrame:mode:{ prototype,cellClass}:numRows:numCols: when the Matrix is 
first initialized. 

See also: - initFrame:, - initFrame:mode:cellClass:numRows:numCols:, 

- initFrame:mode:prototype:numRows:mimCols: 


INSTANCE METHODS 

acceptsFirstMouse 

- (BOOL)acceptsFirstMouse 

Returns NO if the Matrix is in NX_LISTMODE, YES if the Matrix is in any other 
mode. The Matrix does not accept first mouse in NX_LISTMODE. 

action 

- (SEL)action 

Returns the default action of the Matrix. If a Cell which has no action receives an event 
which causes an action message to be sent to a target object (normally an 
NX_MOUSEUP event), this action is sent to the Matrix’s target. 

addCol 

- addCol 

Adds a new column of Cells to the right of the existing columns by invoking 
insertColAt:. New Cells are created with makeCellAt::. Does not redraw even if 
autodisplay is on. If the number of rows or columns in the Matrix has been changed 
via renewRows:cols: then makeCellAt: is invoked only if a new one is needed (since 
renewRowsicols: doesn’t free any Cells). This fact can be used to your advantage 
since you can grow and shrink a Matrix without repeatedly creating and freeing the 
Cells. 

See also: - insertColAt:, - makeCellAt:: 
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addRow 


- addRow 

Adds a new row of Cells at the bottom of the existing rows by invoking insertRowAt:. 
New Cells are created with makeCellAt::. Does not redraw even if autodisplay is on. 
If the number of rows or columns in the Matrix has been changed via renewRows:cols: 
then makeCellAt: is invoked only if a new one is needed (since renewRowsicols: 
doesn’t free any Cells). This fact can be used to your advantage since you can grow 
and shrink a Matrix without repeatedly creating and freeing the Cells. 

See also: - insertColAt:, - makeCellAt:: 

allowEmptySel: 

- allowEmptySel: (BOOL)flag 

If flag is YES, then the Matrix will allow one or zero Cells to be selected. If flag is NO, 
then the Matrix will allow one and only one Cell (not zero Cells) to be selected. This 
setting has effect only in NX_RADIOMODE. 

backgroundColor 

- (NXColor)backgroundCoIor 

Returns the background color of the matrix. 

backgroundGray 

- (float)backgroundGray 

Returns the background gray. A backgroundGray of-1.0 implies no background 
gray; the Matrix is transparent. 

calcSize 

- calcSize 

You never invoke this method. It is invoked automatically by the system if it has to 
recompute some size information about the Cells. It invokes calcDrawInfo: on each 
Cell in the Matrix. Can be overridden to do more if necessary (Form overrides 
calcSize, for example). Returns self. 

See also: - calcSize (Control, Form), - validateSize: 
cellAt:: 

- cellAt: (int)ravy :(int)co/ 

Returns the Cell at row row and column col . 
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cellBackgroundColor 

- (NXColor)cellBackgroundColor 

Returns the background color used to fill the background of a Cell. 

cellBackgroundGray 

- (float)cellBackgroundGray 

Returns the gray value used to fill the background of a Cell before the Cell is drawn. If 
-1.0, then no fill is done behind the Cell before drawing (the cell is transparent). 

cellCount 

- (int)cellCount 

Returns the number of Cells in the Matrix. 

cellList 

- cellList 

Returns the List object that tracks the Cells of the Matrix. 

See also: the List class 

clearSelectedCell 

- clearSelectedCell 

Sets selectedCell to be no selection. Does no drawing. Doesn’t end the previous text 
editing if any and doesn’t invoke selectTextAt::. Will not allow clearing of selected 
Cell if NX_RADIOMODE and an empty selection is not allowed. Returns whatever 
Cell used to be the selectedCell. You rarely invoke this method since 
selectCellAt:-l 1 will clear the selected Cell and redraw. 

See also: - allowEmptySel: 

display 

- display 

Invokes displayFromOpaqueAncestor::: if the Matrix is not opaque and either there 
is an interCell spacing or one or more of the Cells is not opaque. Invokes display::: 
otherwise. The Matrix is considered to be opaque if the backgroundGray is 
non-negative (or if it was setOpaque: explicitly). If cellBackgroundGray is 
non-negative, then all of the Cells are treated as if they were opaque. 
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doesAutosizeCells 

- (BOOL)doesAutosizeCells 

Determines whether Cells will automatically resize when the size of the matrix 
changes. 

doubleAction 

- (SEL)doubleAction 

Returns the action that is sent on a double-click on a Cell in the Matrix. 

drawCell: 

- drawCell :<zCe// 

If aCell is in the Matrix, then it is drawn. Does nothing otherwise. Useful for 
constructs like: [matrix drawCeII:[ [matrix cellAtirow :col] setSomething:args]]]. 

drawCellAt:: 

- drawCell At: (int)rcw :(int)co/ 

Displays the Cell at (row, col ) in the Matrix. 

drawCelllnside: 

- drawCelllnsideiaCe// 

If aCell is in the Matrix, then its inside is drawn (i.e., drawInsideiinView: is invoked 
on the Cell). 

drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

Displays the Cells in the Matrix which intersect any of the rects. 

errorAction 

- (SEL)errorAction 

Returns the action that is sent to the target of the Matrix upon text editing errors. 

See also: setErrorAction: 
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findCellWithTag: 

- findCellWithTag: (mt)anlnt 

Returns the Cell which has a tag matching anlnt. If no Cell in the Matrix matches 
anlnt, then nil is returned. 

See also: - setTag: (ActionCell), - setTag:at::, - setTag:target:action::, 

- selectCellWithTag: 

font 

-font 

Returns the font that will be used to display text in any Cells. 

free 

- free 

Deallocates the storage for the Matrix and all its Cells and returns nil. 

getCellFrame:at:: 

- getCellFrame:(NXRect *)theRect 

at:(int )row 
:(int )col 

Returns the frame of the Cell at the specified row and col. 

getCellSize: 

- getCellSize :(NXSize *)theSize 

Gets the width and the height of the Cells in the Matrix. 

getlntercell: 

- getIntercell:(NXSize *)theSize 

Gets the vertical and horizontal spacing between Cells. 

getNumRows:numCols: 

- getNumRows:(int *)rowCount numCols:(int *)colCount 
Returns, by reference, the number of rows and columns in the Matrix. 
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getRow:andCol:forPoint: 

- getRow:(int *)rmv 

andCol:(int *)col 

forPoint: (const NXPoint *)aPoint 

Returns the Cell at aPoint in the Matrix. If aPoint is outside the bounds of the Matrix 
or in an intercell spacing, getRow:andCol:forPoint: returns nil. Fills *row and *col 
with the row and column position of the Cell. aPoint must be in the Matrix’s coordinate 
system. 

getRow:andCol:ofCell: 

- getRow:(int *)row 

andCol:(int *)col 
ofCell: aCell 

Gets the row and column position of aCell in the Matrix. Fills *row and *col with the 
row and column position of the Cell. Returns the Cell (or nil if aCell is not in the 
Matrix). 

highlightCell At: :lit: 

- highlightCell At: (int)row 

:(int )col 
lit: (BOOL )flag 

Highlights or unhighlights the Cell at {row, col ) in the Matrix by sending the 
highlight:inView:lit: message to the Cell. The focus must be locked on the Matrix. 
Returns self. 

initFrame: 

- initFrame:(const NXRect *)frameRect 

Initializes and returns the receiver, a new instance of Matrix, with default parameters in 
the given frame. The default font is Helvetica 12.0, the default cellSize is 
100.0-by-17.0, the default intercell is 1.0-by-1.0, the default backgroundGray is -1 
(transparent), and the default cellBackgroundGray is -1 . The new Matrix contains no 
rows or columns. The default mode is NX_RADIOMODE. 
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initFr ame: mode: cellClass: numRows: numCols: 

- initFrame: (const NXRect *)frameRect 

mode:(int )aMode 
cellClass icellld 
numRows: (in t)numRows 
numCols : (mt)numCols 

Initializes and returns the receiver, a new instance of Matrix, with numRows rows and 
numCols columns. Sets the Matrix’s mode to aMode. aMode can be one of four 
constants: 

NX_TRACKMODE Just track the mouse inside the Cells 

NX_HIGHLIGHTMODE Highlight the Cell, then track, then unhighlight 
NX_RADIOMODE Allow no more than one selected Cell 

NX_LISTMODE Allow multiple selected Cells 

These constants are described in the “CLASS DESCRIPTION.” The new Matrix adds 
new Cells by sending alloc and init messages to the Cell subclass represented by 
classld (the value returned when sending a class message to Cell or a subclass of Cell). 

This method is the designated initializer for Matrices that add Cells by creating 
instances of a Cell subclass. 

initFrame: mode: prototype: numRows: numCols: 

- initFrame: (const NXRect *)frameRect 

mode:(int )aMode 
prototype :aCell 
numRows: (int )numRows 
numCols: (int )numCols 

Initializes and returns the receiver, a new instance of Matrix, with numRows rows and 
numCols columns. Sets the Matrix’s mode to aMode. aMode can be one of the four 
constants listed in the previous method. 

These constants are described in the “CLASS DESCRIPTION.” The new Matrix adds 
new Cells by copying aCell, and instance of Cell or a subclass of Cell. If you do not 
plan to add any more Cells to this Matrix, invoke [[matrix setPrototypemil] free] after 
creating the Matrix. 

This method is the designated initializer for Matrices that add Cells by copying an 
instance of a Cell subclass. 
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insertCoIAt: 


- insertColAt:(int)co/ 

Inserts a new column of Cells before column col. New Cells are created with 
makeCellAt::. This method doesn’t redraw even if autodisplay is on. Most of the 
time, you’ll want to perform sizeToCells after performing this method to resize the 
Matrix View to fit the newly added Cells. Returns self. 

insertRowAt: 

- insertRowAt: (int)row 

Inserts a new row of Cells before row row. New Cells are created with makeCellAt::. 
This method doesn’t redraw even if autodisplay is on. Most of the time, you’ll want to 
perform sizeToCells after performing this method to resize the Matrix View to fit the 
newly added Cells. Returns self. 

isBackgroundTransparent 

- (BOOL)isBackgroundTransparent 

Returns YES if the Matrix background is transparent, NO otherwise. 

isCellBackgroimdTransparent 

- (BOOL)isCellBackgroundTransparent 

Returns YES if Cells in the Matrix are created with transparent backgrounds, NO 
otherwise. 

makeCellAt:: 

- makeCellAt: (int)raw :(int)col 

If there is a protoCell, then it is cloned by sending it a copy message; otherwise, a new 
Cell is created by sending new to the class object referenced by the cellClass instance 
variable. You never invoke this method directly; it’s invoked by addRow and other 
methods. It may be overridden if desired. 

See also: - addCol, - addRow, - insertCoIAt:, - insertRowAt: 
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mouseDown: 


- mouseDown :(NXEvent *)theEvent 

You never invoke this method but may override it to implement subclassses of the 
Matrix class. The response of the Matrix depends on the mode set when it was first 
initialized: 

In NX_TRACKMODE, each Cell is given the opportunity to track the mouse while it 
is in its bounds. 

In NX_HIGHLIGHTMODE, each Cell is given the opportunity to track the mouse 
while it is in its bounds and the currently tracking Cell is highlighted. 

In NX_RADIOMODE, each Cell is given the opportunity to track the mouse while it 
is in its bounds, the currently tracking Cell is highlighted, and no more than one Cell 
can have a non-zero state at any time. 

In NX_LISTMODE, Cells are not given the opportunity to track the mouse, rather, they 
are merely highlighted as the mouse is dragged over them. Shift-mousedown can be 
used to extend the selection, Command-mousedown can be used to make disjoint 
selections. 

In any mode, a mousedown in an editable Cell immediately enters text editing mode. 
Also, a double-click in any Cell sends the doubleAction to the target in addition to the 
regular action. 

See also: - initFrame:mode:ceHClass:numRows:numCols:, 

- mitFrame:mode:prototype:numRows:numCols: 

mouseDownFlags 

- (int)mouseDownFlags 

Returns the flags (e.g., NX_SHIFTMASK) that were in effect when the mouse went 
down to start the current tracking session. Use this method if you want to access these 
flags, but don’t want the overhead of having to add NX_MOUSEDOWNMASK to the 
sendActionOn: mask in every Cell to get them. This method is valid only during 
tracking; it’s not useful if the target of the Matrix initiates another Matrix tracking loop 
as part of its action method. 

perfor mKey Equivalent: 

- (BOOL)performKeyEquivalent:(NXEvent *)theEvent 

Returns YES if a Cell in the matrix responds to the key equivalent in theEvent, NO if 
no Cell responds. If a Cell responds to the key equivalent, it is sent the messages 
highlight:inView:lit:YES, then incrementState, and finally 

highlight:inView:lit:NO. You do not send this message; it is sent when the Matrix or 
one of its superviews is the first responder and the user presses a key. 
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prototype 

- prototype 

Returns the prototype Cell set by initFrame:mode:prototype:numRows:numCols: 
or setPrototype:. 

See also: - initFrame:mode:prototype:numRows:numCols:, - setPrototype: 

putCelhat:: 

- putCell:«ewCe// 

at:(int)ww 

:(mi)col 

Replaces the Cell at {row, col) by newCell, and returns the old Cell at that position. 
Draws the new Cell if autodisplay is on. 

read: 

- read :(NXTypedStream *)stream 

Reads the Matrix from the typed stream stream. Returns self. 

removeColAtrandFree: 

- removeCoIAt:(int)ce>/ andFree : {BOOL)flag 

Removes the column at position col. If flag is YES then the Cells in that column are 
freed. Doesn’t redraw even if autodisplay is on. You normally need to invoke 
sizeToCells after invoking this method to resize the Matrix to fit the reduced Cell count. 
Returns self. 

removeRowAtiandFree: 

- removeRowAt:(int)row andFree: (B OOL)flag 

Removes the row at position row. If flag is YES then the Cells in that column are freed. 
Doesn’t redraw even if autodisplay is on. You normally need to invoke sizeToCells 
after invoking this method to resize the Matrix to fit the reduced Cell count. Returns 
self. 
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renewRowsrcols: 


- renewRows:(int )newRows cols:(int )newCols 

Changes the number of rows and columns in the Matrix, but uses the same Cells as 
before (creates new Cells if the new size is larger). Since renewing the number of rows 
and columns often requires that the size of the Matrix itself change (by sending a 
sizeToCells message, for example), renewRowsicols: doesn’t automatically display 
the Matrix even if autodisplay is on. You will normally want to invoke sizeToCells to 
resize your Matrix View after invoking this method. The selectedCell is cleared. 
Returns self. 

resetCursorRects 

- resetCursorRects 

Cycles through the Cells asking each to resetCursorRectsrinView:. If one of the Cells 
has a cursor rectangle to set up, it will send the message addCursorRecticursor: back 
to the Matrix. Returns self. 

scr ollCellT o V isible:: 

- scrollCellTo Visible: (int)rovv :(int)co/ 

If the Matrix is in a scrolling view, then the Matrix will scroll to make the Cell at 
(row, col ) visible. Returns self. 

select All: 

- selectAll: sender 

If the mode of the Matrix is not NX_RADIOMODE, then all the Cells in the Matrix are 
selected. The currently selected Cell is unaffected. Editable Cells are not affected. The 
Matrix is redisplayed. Returns self. 

See also: - selectText:, - selectCellAt:: 

selectCell: 

- selectCel Y.aCell 

If aCell is in the Matrix, then the Cell is selected, the Matrix is redrawn, # and the 
selected Cell is returned. Returns nil if the Cell is not in the Matrix. 
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selectCellAt:: 


- selectCellAt:(int)rcw :(int )col 

Sets selectedCell to be the Cell at (row, col), selectedRow to be row and selectedCol 
to be col. Ends any editing going on in the window and invokes selectTextAt:raw :col 
if the Cell at (row, col). If row or col is -1, then the current selection is cleared (unless 
the Matrix is in NX_RADIOMODE and does not allow empty selection). Redraws the 
affected Cells and returns self. 

seleetCellWithTag: 

- seleetCellWithTag :(mt)theTag 

Finds the Cell in the Matrix with the given tag and selects it. Returns the Matrix id or 
nil if no Cell has theTag. 

selectedCell 

- selectedCell 

Returns the currently selected Cell. 

selectedCol 

- (int)selectedCoI 

Returns the column number of the currently selected Cell. If Cells in multiple columns 
are selected, this method returns the number of the last column in which a cell was 
selected. If no Cells are selected, this method returns -1. 

selectedRow 

- (int)selectedRow 

Returns the row number of the currently selected Cell. If Cells in multiple rows are 
selected, this method returns the number of the last row in which a cell was selected. If 
no Cells are selected, this method returns -1. 

selectText: 

- selectText: sender 

Selects the text of an editable Cell in the Matrix, if any. If sender is nextText, the first 
Cell is selected; otherwise, the last Cell is selected. Don’t invoke this method before 
inserting the receiving Matrix in a window’s view hierarchy and drawing it. Returns 
self. 
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selectTextAt:: 


- selectTextAt: (int)row :(int )col 

Select the text of the Cell at {row, col) in the Matrix if any. Don’t invoke this method 
before inserting the receiving Matrix in a window’s view hierarchy and drawing it. 
Returns self. 

sendAction 

- sendAction 

If the selected Cell has an action and a target, its action is sent to its target. If the Cell 
has an action but no target, its action is sent to the Matrix’s target. If the Cell doesn’t 
have an action or target, the Matrix’s action is sent to its target. 

See also: - action, - setAction:, - setTarget:, - target 
sendAction:to: 

- sendAction :(SEL )theAction toitheTarget 

Sends the Action to theTarget and returns self. You don’t normally invoke this method. 
It is invoked by event handling methods such as Cell’s trackMouse:inRect:ofView: to 
send an action to a target in response to an event within the Matrix. 

sendAction:to:forAHCells: 

- sendAction :(SEL )aSelector 

toianObject 

for AllCells: (B OOL)flag 

Repeatedly sends the message [ anObject aSelector:aCell] for each Cell in the matrix. 
The process begins with aCell being the Cell in the first row and column of the Matrix 
and proceeds row by row. If the flag is NO, then only highlighted Cells are sent in the 
message; this is useful for performing actions when multiple Cells are selected in an 
NX_LISTMODE Matrix. The method aSelector should return YES if it wants to 
continue looping for remaining cells, NO otherwise. 

Note: This method is not invoked to send action messages to target objects in response 
to mouse-down events in the Matrix. Instead, you can invoke it if you want to have 
multiple Cells in a Matrix interact with an object. 

This method returns self. 
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send Double Action 

- sendDoubleAction 

You don’t invoke this method; it is sent in response to a double-click event in the 
Matrix. The method sends an action message to a target object, depending on the 
actions and targets of the Matrix and the selected Cell. If the selected Cell has an 
action, then it sends that action to the selected cell’s target. Otherwise, if the Matrix 
has a doubleAction message, it sends that message to the Matrix’s target. Finally, if 
the Matrix doesn’t have a doubleAction, it sends the Matrix’s action to its target. 
Returns self. 

set Action: 

- set Action : (SEL)aSelector 

Sets the default action of the Matrix. If it has an action, a Cell in the Matrix can respond 
to certain events (usually NX_MOUSEUP events) within its frame by sending its action 
to its target. If a Cell doesn’t have an action, the Matrix can respond to the event by 
sending its action to its target (not to the Cell’s target). This method sets the action sent 
by the Matrix in such cases. Returns self. 

s 

setActionrat:: 

- setAction:(SEL)<25Wccfor 

at:(int)raw 
:(int )col 

Sets the action of the Cell at (row, col ) to aSelector. Returns self. 

set Autoscroll: 

- set Autoscroll : (BOOL)flag 

If flag is YES and the Matrix is in a scrolling view, it will be autoscrolled whenever a 
the mouse is dragged outside the Matrix after a mouse-down event within its bounds. 
Returns self. 

setAutosizeCells: 

- setAutosizeCells:(BOOL)/7ag 

Sets Cells in the Matrix to automatically resize when the size of the Matrix 
changes. Returns self. 
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setBackgroundColor: 

- setBackgroundColor: (NXColor )Colorvalue 

Sets the background color for the Matrix. This is the color used to fill the space 
between Cells or the space behind any non-opaque Cells. If autodisplay is on, the entire 
Matrix is redrawn. Returns self. 

setBackgroundGray: 

- setBackgroundGray: (float) value 

Sets the background gray for the Matrix (a backgroundGray of -1.0 means there is no 
background gray: the Matrix is transparent). This is the gray used to fill the spaces 
between Cells or the space behind any non-opaque Cell if cellBackgroundGray is 
-1.0. If autodisplay is on, the entire Matrix is redrawn. Returns self. 

See also: - backgroundGray 

setBackgroundTransparent: 

- setBackgroundGray: (BOOL )flag 

Sets the background of the Matrix to transparent. With the background transparent, the 
spaces between Cells are transparent, as is the space behind any non-opaque Cell. If 
autodisplay is on, the entire Matrix is redrawn. 

See also: - isBackgroundTransparent 

setCellBackgroundColor: 

- setCellBackgroundColor :(NXColor )value 

Sets the background color for the Cells. If autodisplay is on, the entire Matrix is 
redrawn. 

setCellBackgroundGray: 

- setCellBackgroundGray: (float) value 

Sets the background gray for the Cells. If value is -1.0, then no background gray is 
drawn behind the Cells. If autodisplay is on, the entire Matrix is redrawn. 

setCellBackgroundTransparent: 

- setCeHBackgroundTransparent:(BOOL)//<3g 

Sets the background of the Cells to transparent. If autodisplay is on, the entire Matrix 
is redrawn. 

See also: - isCellBackgroundTransparent 
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setCellClass: 


- setCellClassic/a^/J 

Sets the cellClass instance variable to classld, the value returned by sending a class 
message to Cell or a subclass of Cell. This class will be used by makeCellAt: : to create 
new Cells if there is no prototype Cell. The default is set with the setCellClass: class 
method. 

See also: + setCellClass:, - setPrototype: 
setCellSize: 

- setCellSize: (const NXSize *)aSize 

Sets the width and the height of each of the Cells. Does not redraw the Matrix (even if 
autodisplay is on). 

setDouble Action: 

- setDoubleAction:(SEL)<3>Sc/cctor 

Sets aSelector as the action to be sent to the Matrix’s target (in addition to the regular 
action) when the user double-clicks on a Cell. If there is no doubleAction, then 
double-clicks are treated as single-clicks. Setting a double action also sets 
allowMuItiClick: to YES. Returns self. 

See also: - allowMuItiClick: 

set Ena bled: 

- setEnabled:(BOOL)y?ag 

If flag is YES, enables all Cells in the Matrix; if NO, disables all Cells. If autodisplay 
is on, this redraws the entire Matrix. Returns self. 

setError Action: 

- setErrorAction:(SEL)aSc/ector 

Sets aSelector as the action sent to the target of the Matrix when any text editing errors 
occur. An error can occur when the user types something into a Cell and the value 
returned when isEntryAcceptable: is sent to the Cell is NO. This is a convenient 
method for enforcing some restrictions on what a user can type into a Cell. However, 
if you want to impose some restriction such as a range restriction (e.g., a typed number 
must be within some bounds), it is probably more convenient simply to check the value 
in your action method and, if it is not acceptable, invoke selectTextAt::) to notify the 
user that the value must be retyped. Returns self. 
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setFont: 


- setFont ifontObj 

Sets the font of the Matrix to fontObj. This will cause all current Cells to have their 
font changed to fontObj as well as cause all future Cells to have that font. If autodisplay 
is on, this redraws the entire Matrix. Returns self. 


setIcon:at:: 

- setlcon: (const char *)iconName 
at:(int )row 
:(int )col 

Sets the icon of the Cell at (row, col ) to iconName. If autodisplay is on, then the Cell 
is redrawn. Returns self. 

See also: - setlcon: (ButtonCell, Cell) 


setlntercell: 

- setlntercell: (const NXSize *)aSize 

Sets the width and the height of the space between Cells without redrawing the Matrix, 
even if autodisplay is on. Returns self. 


setMode: 

- setMode :(int )aMode 

Sets the mode of the Matrix. aMode can be one of four constants: 


Just track the mouse inside the Cells 
Highlight the Cell, then track, then unhighlight 
Allow no more than one selected Cell 
Allow multiple selected Cells 

See also: - mouseDown: 


NX_TRACKMODE 

NX_HIGHLIGHTMODE 

NX_RADIOMODE 

NXJLISTMODE 


setNextText: 

- setNextText :anObject 

Sets the nextText instance variable. When the user presses the Tab key while the last 
editable entry of the Matrix is being edited, the selectText: method is sent to the object 
represented by nextText. A backwards link is automatically created, so that pressing 
Shift-Tab will move backwards to the previous text via setPreviousText:. Returns self. 
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setPreviousT ext: 

- setPre\iousText:anObject 

Normally you never invoke this method. It is invoked automatically by some other 
object’s setNextText: method. It sets the object which will be sent selectText: when 
Shift-Tab is pressed in the Matrix and there are no more fields. Returns self. 

setPrototype: 

- setPrototype-.aCe// 

Sets the protoCell instance variable to aCell and returns the id of the previous 
protoCell. As the new prototype, aCell is copied to make any future Cells added to the 
Matrix. 

If you implement your own Cell subclass, then instantiate it as the prototype for your 
Matrix and make sure your Cell does the right thing when it receives a copy message. 
For example, remember that Object’s copy copies only pointers, not what they point 
to—sometimes this is what you want, sometimes not. The best way to implement copy 
when you subclass Cell is to invoke [super copy], then copy instance variable values in 
your subclass individually. Be especially careful that freeing the prototype will not 
damage any of the copies that were made and put into the Matrix (for example, due to 
shared pointers). 

To stop prototyping, invoke this method with nil as the argument, then free the old 
prototype Cell if no more Cells of that type will be created. If you want to use a 
prototype cell in other places in the application, it may be useful to copy your prototype 
when invoking this method, for example: 


myCellPrototype = [[myCell alloc] init]; 
[myMatrix setPrototype:[myCellPrototype copy]]; 


This prevents your version of the prototype from being freed when the Matrix is freed. 

setReaction: 

- setReaction : (BOOL)flag 

If flag is NO, prevents the cell from changing back to its previous state; if YES, allows 
it to revert to reflect unhighlighting. Invoke this from an action method if the action 
causes the Cell to change in such a way that trying to unhighlight it would be incorrect; 
for example, if the Cell is deleted or its visual appearance completely changes. Returns 
self. 
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setScrollable: 


- setScrollable :(BOOL)flag 

Sets all the Cells to be scrollable. Returns self. 

See also: - setScrollable: (Cell) 

setState:at:: 

- setState:(int)v< 2 /«e 

at:(int)row 

:(int)c6>/ 

Sets the state of the Cell at row row and column col to value. For NX_RADIOMODE 
Matrices, this is identical to selectCellAt:: except that the state can be set to any 
arbitrary value. If autodisplay is on, redraws the affected Cell; if the Matrix is in 
NX_RADIOMODE, the Cell is redrawn regardless of the setting of autodisplay. 
Returns self. 

setTag:at:: 

- setTag:(int)rm/wf 

at:(int)row 

\(\ni)col 

Sets the tag of the Cell at (row, col) to anlnt and returns self. 

setTag:target:action:at:: 

- setTag:(int)rm/«r 

target ’.anObject 
action: (SEL )aS elector 
at:(int)rcw 
:(int )col 

Sets the tag, target object and action method of the Cell at row row and column col. 
Returns self. 

setTarget: 

- setTarget :anObject 

Sets the target object of the Matrix. This is the target to which actions will be sent 
during tracking in any Cells that do not have their own target. Returns self. 

See also: - action, - setAction, - target 
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setTarget:at;: 

- setTarget lanObject 

at:(in t)row 
:(int )col 

Sets the target of the Cell at row row and column col to anObject. Returns self. 

setTextDelegate: 

- setTextDelegate:<2«06/<?c/ 

Sets the object to which the Matrix will forward any messages from the field editor (for 
example, textiisEmpty:, textWillEnd:, textDidEndiendChar:, textWillChange: 
and textDidChange:). Returns self. 

See also: the Text class 

setTitle: at:: 

- setTitle: (const char *)aString 

at:(int )row 
:(int )col 

Invoke this method to set the title of the Cell at row row and column col to aString. If 
autodisplay is on, then the Cell is redrawn. Returns self. 

See also: - setTitle: (ButtonCell) 

sizeTo:: 

- sizeTo: (float) width :(float )height 

If editing is going on in the Matrix, this aborts the editing, then, after the View is 
resized, reselects the text to allow editing to continue. Returns self. 

sizeToCells 

- sizeToCells 

Changes the width and the height of the Matrix frame so that the Matrix’s frame 
contains exactly the Cells. Does not redraw the Matrix. Returns self. 

sizeToFit 

- sizeToFit 

Changes cellSize to accommodate the Cell with the largest contents in the Matrix. 
Then changes the width and the height of the Matrix frame so that the Matrix’s frame 
contains exactly the Cells. Doesn’t redraw the Matrix. Returns self. 
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target 

- target 

Returns the id of the Matrix’s target object. 

See also: - setTarget:. 

textDelegate 
, - textDelegate 

Returns the id of the Matrix’s text delegate: the object that receives messages from the 
field editor. The field editor is the Text object used to draw text in all cells in the 
window. Messages are forwarded to the text delegate by the Matrix. 

See also: - getFieldEditor:for: (Window) 

textDidChange: 

- textDidChange itextObject 

This message is forwarded to the textDelegate if the Matrix has one. 

See also: - textDelegate 

textDidEnd: endChar: 

- textDidEnditextObject endChar:(unsigned shori)whyEnd 

Invoked automatically by the system when the text editing ends. If editing ends 
because the Return key is pressed, then the message [self sendAction] is sent. To get 
the id of the Cell in which editing is being performed, use the selectedCell method; to 
access its row or column, use selectedRow or selectedCol. If editing ends because the 
Tab key is pressed and the Cell being edited was not the last in the Matrix, then the next 
Cell is selected. If the Cell is the last one and the nextText instance variable is nil, the 
first Cell in the Matrix is selected. Otherwise the selectText: message is sent to the 
object stored in nextText. The textDelegate (if any) is sent the textDidEnd:endChar: 
message. Returns self. 

textDidGetKeys:isEmpty: 

- textDidGetKeys itextObject isEmpty:(BOOL )flag 

Forwarded to the textDelegate (if any). Returns self. 
textWillChange: 

- (BOOL)textWillChang eitextObject 
Forwarded to the textDelegate (if any). Returns self. 
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textWillEnd: 


- (BOOL)textWilIEnd:texf0&/ecr 

Invoked automatically by the system before text editing ends. It sends the error Action 
to the target if isEntryAcceptable:. The textDelegate gets a chance to cancel as well. 
Returns self. 


validateSize: 

- validateSize:(BOOL)/7<2g 

Allows control over whether the Matrix will invoke calcSize the next time it draws. If 
flag is YES, then the size information in the Matrix is assumed correct and will not be 
recomputed. If flag is NO, then calcSize will be invoked before any further drawing is 
done. Returns self. 

See also: -calcSize: 


write: 

- write :(NXTypedStream *)stream 

Writes the receiving Matrix to the typed stream stream. Returns self. 


CONSTANTS AND DEFINED TYPES 

/* Matrix Constants */ 

#define NX_RADIOMODE 0 

#define NX_HIGHLIGHTMODE 1 
fdefine NX_LISTMODE 2 

tdefine NX TRACKMODE 3 


2-294 Chapter 2: Class Specifications 



Menu 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN appkit/Menu.h 

CLASS DESCRIPTION 

The Menu class defines a Panel that contains a single Control object: a Matrix that 
displays a list of MenuCells. 

There are methods for adding both command and submenu items to the Menu. The 
Menu window can be resized to exactly fit the matrix. 

Exactly one Menu created by the application is designated as the “main menu” for the 
application. This Menu is displayed on top of all other windows whenever the 
application is active, and it has no close box. 

Menus can be made submenus of other menus. A submenu is associated with a 
particular item in another menu, its “supermenu.” Whenever the user clicks the item, 
the submenu it controls is brought to the screen and “attached” to the controlling 
supermenu. An item can control only one submenu. 

Note that you can drag Menus into your application from Interface Builder’s Palettes 
panel. Several menu items are initialized to work correctly without any additional 
effort on your part. You can easily set other menu items to display the commands and 
perform the actions associated with your specific application. 


INSTANCE VARIABLES 

Inherited from Object 
Inherited from Responder 
Inherited from Window 


Class 

id 

NXRect 

id 

id 

id 

id 

id 

id 

id 

int 

int 

float 

struct _wFlags 
struct _wFlags2 


isa; 

nextResponder; 

frame; 

contentView; 

delegate; 

firstResponder; 

lastLeftHit; 

lastRightHit; 

counterpart; 

fieldEditor; 

winEventMask; 

windowNum; 

backgroundGray; 

wFlags; 

wFlags2; 
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Inherited from Panel 


(none) 


Declared in Menu 


supermenu 

matrix 

attachedMenu 

lastLocation 

reserved 

menuFlags.sizeFitted 
menuFlags .autoupdate 
menuFlags.attached 
menuFlags.tomOff 
menuFlags. was Attached 
menuFlags. wasTomOff 

METHOD TYPES 

Creating a Menu zone 

Initializing a new Menu 


id 

id 

id 

NXPoint 

id 

struct _menuFlags { 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 

} 


supermenu; 

matrix; 

attachedMenu; 

lastLocation; 

reserved; 

sizeFitted: 1; 
autoupdate: 1; 
attached: 1; 
tomOff: 1; 
wasAttached: 1; 
wasTornOff:l; 
menuFlags; 


The Menu that this Menu is a submenu of. 


The Matrix object used to hold MenuCells. 

The submenu that is currently attached to this 
Menu. When the user moves or closes a Menu, 
the attached submenu performs with it. 

Last menu location. 


Reserved for future use. 


Set if the menu has been sized to fit the matrix. 


Set if the menu wants automatic updating. 

Set if the menu is attached to its supermenu. 

Set if the menu has been tom off of its supermenu. 
Set if the menu was attached before tracking. 

Set if the menu was tom off before tracking. 


+ menuZone 
+ setMenuZone: 


- init 

- initTitle: 
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Setting up the commands 

- addItem:action:key Equivalent: 

- findCell WithTag: 

- itemList 

- setltemList: 

- setSubmenu:forItem: 

- submenuAction: 

Managing menu windows 

- close 

- getLocation:forSubmenu: 

- moveTopLeftTo:: 

- sizeToFit 

- windowMoved: 

Displaying the Menu 

- display 

- set Autoupdate: 

- update 

Handling events 

- mouseDown: 

- rightMouseDown: 

Archiving 

- awake 

- read: 

- write: 


CLASS METHODS 

menuZone 

+ (NXZone *)menuZone 

Creates and returns a zone with the name “Menus” in which to allocate new Menus. 
After invoking this method, you should allocate new Menu instances from this zone. 

See also: - alloc (Object) 
setMenuZone 

+ setMenuZone: (NXZone *)aZone 

Sets the zone from which menus will be allocated to aZone. 

See also: - alloc (Object) 
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INSTANCE METHODS 


addltem :action: keyEqui valent: 

- addltem: (const char *)aString 

action : (SEL )aS elec tor 
keyEquivalent: (unsigned short )charCode 

Creates a new MenuCell, appends it to the receiving Menu, and returns the id of the 
new cell. 

The MenuCell displays aString as the command name for the menu item. aSelector is 
the action method the command will invoke. The key equivalent charCode becomes 
the key equivalent for the cell. 

The new MenuCell’s target is nil, it’s automatically enabled, and it has no tag or 
alternate character string to display. You can change these and other properties of the 
Cell, including the submenu attribute, by sending direct messages to the returned id. 

This method doesn’t automatically redisplay the Menu. Upon the next display 
message, the menu is automatically sized to fit. 

See also: - setSubmenu:forItem: 

awake 

- awake 

Reinitializes and returns a Menu as it’s unarchived. Do not invoke this method directly; 
it’s invoked by the read: method. 

close 

- close 

Overrides Panel’s close method. If a submenu is attached to the Menu, the attached 
submenu is also removed from the screen. 

See also: - close (Window) 

display 

- display 

This overrides window’s display method to provide automatic size-to-fit of the menu 
window to its matrix. All changes to the matrix that go through the menu methods 
cause a resizing the next time the Menu is displayed. 

See also: - sizeToFit 
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findCellWithTag: 

- findCellWithTag :(int)aTag 

Returns the MenuCell that has aTag as its tag; returns nil if no such cell can be found. 

getLocation: for Submenu: 

- getLocation :(NXPoint *)theLocation forSubmenu laSubmenu 

This message is sent whenever the submenu location is needed. By default, the 
submenu is to the right of its supermenu, with its titlebar aligned with the supermenu’s. 
You never directly use this method, but may override it to cause the submenu to be 
attached with a different strategy. 


init 

- init 

Initializes and returns the receiver, a new instance of Menu, displaying the title “Menu.” 
All other features are as described in the initTitle: method below. 

initTitle: 

- initTitle: (const char *)aTitle 

Initializes and returns the receiver, a new instance of Menu, displaying the title aTitle. 
The Menu is positioned in the upper left comer of the screen. The Menu’s Matrix is 
initially empty. 

The Menu is created as a buffered window initially out of the Window Server’s screen 
list. It must be sent one message to display itself (into the buffer), and another message 
to move itself on-screen before it will be visible. 

The Menu has a style of NX_MENUSTYLE and it has an NX_CLOSEBUTTON 
button mask. The button isn’t shown until the Menu is tom off of its supermenu. 

A default matrix is created to contain MenuCell items to display without any 
intervening space in a single column. The Matrix will use 12-point Helvetica by default 
to display the items. The matrix will be empty. 

Items can be added to the Menu through the addItem:action:keyEquivalent: method. 
The action and key equivalent may both be null. To make a submenu, a 
setSubmenu:foiTtem: message is sent directly to the Menu. 

All Menus have an event mask that excludes keyboard events; they therefore will never 
become the key window or main window for your application. 

See also: - addItem:action:keyEquivalent: 
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itemList 

- itemList 

Returns the matrix of MenuCells used by the Menu. 

mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Overrides the View method to allow MenuCell to delegate tracking control to the 
Menu. Returns self. 

moveTopLeftTo:: 

- moveTopLeftTo: (NXCoord).r :(NXCoord)y 

Repositions the Window on the screen. The arguments specify the new location of the 
Window’s top left comer—the top left comer of its frame rectangle—in screen 
coordinates. 

See also: - dragFrom::eventNum: (Window), - moveTo:: (Window) 
read: 

- read:(NXTypedStream *)stream 

Reads the Menu from the typed stream stream. Returns self, 
r ightMouseDown: 

- rightMouseDown :(NXEvent *)theEvent 

Saves the current state of the menu (and its submenus), and pops it up under the mouse 
position. The menu is tracked as normal, and then the menu’s state is restored. 

set Autoupdate: 

- set Autoupdate: (B OOL)flag 

If flag is YES, the menu will respond to the update message sent by the Application to 
all visible Windows after each event (if Application’s autoupdating has been enabled). 
If NO, the Menu won’t respond. 

See also: - update 


2-300 Chapter 2: Class Specifications 



setltemList: 


- setltemLisUaMatrix 

Sets the Menu’s Matrix to aMatrix. Subsequent display will size to fit. The previous 
Matrix is returned. 

setSubmenu :forItem: 

- setSubmenuiaMenu forltem: aCell 

Sets aMenu as the submenu controlled by the MenuCell aCell. 

sizeToFit 

- sizeToFit 

Adjusts the size of the Menu window to its Matrix subview so that they exactly 
encompass all the commands. Use this method after you’re through adding items, 
modifying the strings they display, or altering the font used to display them. When the 
Menu is resized, its upper left comer remains fixed. After any resizing that might be 
necessary, this method will redisplay the Menu. 

See also: - sizeToFit (Matrix) 

submenu Action: 

- submenu Action '.sender 

This message is the action message sent to a submenu by the MenuCell attached to that 
submenu. If sender is in a visible Menu, this action message causes the receiving Menu 
to attach itself to the menu containing sender. Returns self. 

update 

- update 

Sent to Menu to have the menu update its display. It does this by getting the 
update Action for each cell and sending it to NXApp. If the updateMethod returns 
YES, the Menu’s Matrix is told to redraw the cell using drawCellAt::. For this method 
to have any effect, you must have sent a prior setAutoupdate:YES message. 

See also: - setUpdate: 
windowMoved: 

- windowMoved :(NXEvent *)theEvent 

Overrides Window method to detach the receiving Menu from its supermenu. 

See also: - windowMoved: (Window) 
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write: 

- write:(NXTypedStream *)stream 

Writes the receiving Menu to the typed stream stream and returns self. 

METHODS IMPLEMENTED BY THE DELEGATE 

submenuAction: 

- submenuAction '.sender 
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MenuCell 


INHERITS FROM ButtonCell: ActionCell: Cell: Object 

DECLARED IN appkit/MenuCell.h 

CLASS DESCRIPTION 

MenuCell is a subclass of ButtonCells that appear in Menus. They draw their text 
left-justified and show an optional key equivalent or submenu arrow on the right. 


INSTANCE VARIABLES 

Inherited from Object 
Inherited from Cell 


Inherited from ActionCell 


Inherited from ButtonCell 


Declared in MenuCell 
updateAction 


Class 

char 

id 

struct _cFlagsl 
struct _cFlags2 

int 

id 

SEL 

char 

union _icon 
id 

struct _bcFlagsl 
struct _bcFlags2 
unsigned short 
unsigned short 

SEL 


isa; 

*contents; 

support; 

cFlagsl; 

cFlags2; 

tag; 

target; 

action; 

*altContents; 

icon; 

sound; 

bcFlagsl; 

bcFlags2; 

periodicDelay; 

periodiclnterval; 

updateAction; 


Action used to keep MenuCell’s enabled state in 
synch with the Application. 


METHOD TYPES 

Initializing a new MenuCell 

Setting the Update Action 

Querying the MenuCell 


- init 

- initTextCell: 

- setUpdateActiomforMenu: 

- updateAction 

- hasSubmenu 
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Tracking the Mouse 
Setting User Key Equivalents 

Archiving 


- trackMouse:inRect:ofView: 

+ useUserKey Equivalents: 

- userKeyEquivalent 

- read: 

- write: 


INSTANCE METHODS 

hasSubmenu 

- (BOOL)hasSubmenu 

Return YES if the MenuCell invokes a submenu, NO otherwise. 


init 


- init 


Initializes and returns the receiver, a new instance of MenuCell, with the default title 
“Menultem.” 


initTextCell: 

- initTextCell: (const char *)aString 


Initializes and returns the receiver, a new instance of MenuCell, with aString as its title. 
This method is the designated initializer for the MenuCell class; override this method 
if you create a subclass of MenuCell that performs its own initialization. 


read: 

- read:(NXTypedStream *)stream 

Reads the MenuCell from the typed stream stream. Returns self. 


2-304 Chapter 2: Class Specifications 



setU pdate Action: forMenu: 

- setUpdateAction :(SEL)aSelector forMenu :aMenu 

Sets the updateAction for the MenuCell. The updateAction is a method that when 
invoked should set the MenuCell to reflect the current state of the application. This may 
include enabling or disabling the item, changing the string displayed, or setting the 
item’s state. The updateAction takes a single argument, the id of the Cell to update. 

The updateAction shouldn’t redisplay the Cell itself. Rather it should return YES or 
NO depending upon whether the Cell needs to be redisplayed. 

When an updateAction is set for a MenuCell, the Menu passed in aMenu is set so it 
will be automatically updated after each event is processed. 

See also: - update: (Menu), - updateWindows: (Application) 

trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent *)theEvent 

inRect:(const NXRect *)cellFrame 
ofView icontrolView 

Delegates the first event it gets to the Menu. All mouse tracking is handled by Menu. 

updateAction 

- (SEL)updateAction 

Returns selector for the updateAction method. 

userKeyEquivalent 

- userKeyEquivalent 

Returns the user-assigned key equivalent for the receiving MenuCell. 

useUserKeyEquivalents: 

+ useUserKeyEquivalents: (BOOL)flag 

If flag is YES, then MenuCells can accept user key equivalents. If NO, user key 
equivalents are disabled. 

write: 

- write :(NXTypedStream *) stream 

Writes the receiving MenuCell to the typed stream stream and returns self. 
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NXBitmapImageRep 


INHERITS FROM NXImageRep : Object 

DECLARED IN appkit/NXBitmapImageRep.h 


CLASS DESCRIPTION 

An NXBitmapImageRep is an object that can render an image from bitmap data. The 
data can be in Tag Image File Format (TIFF), or it can be raw image data. If it’s raw 
data, the object must be informed about the structure of the image—its size, the number 
of color components, the number of bits per sample, and so on—when it’s first 
initialized. If it’s TIFF data, the object can get this information from the various TIFF 
fields included with the data. 

Although NXBitmapImageReps are often used indirectly, through instances of the 
NXImage class, they can also be used directly—to render bitmap images or to produce 
TIFF representations of them. 


Setting Up an NXBitmapImageRep 

A new NXBitmapImageRep is passed bitmap data for an image—or told where to find 
it—when it’s first initialized: 

• TIFF data can be read from a stream, from a file, or from a section of the_TIFF 

segment of the application executable. If it’s stored in a section or a separate file, 
the object will delay reading the data until it’s needed. 

• Raw bitmap data is placed in buffers, and pointers to the buffers are passed to the 
object. 

An NXBitmapImageRep can also be created from bitmap data that’s read from an 
existing (already rendered) image. The object created from this data is able to 
reproduce the image. 

Although the NXBitmapImageRep class inherits NXImageRep methods that set image 
attributes, these methods shouldn’t be used. Instead, you should either allow the object 
to find out about the image from the TIFF fields or use methods defined in this class to 
supply this information when the object is initialized. 
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TIFF Compression 

TIFF data can be read and rendered after it has been compressed using any one of the 
three schemes briefly described below: 

LZW Compresses and decompresses without information loss, 

achieving compression ratios of anywhere from 2:1 to 3:1. It may 
be somewhat slower to compress and decompress than the 
PackBits scheme. 

PackBits Compresses and decompresses without information loss, but may 
not achieve the same compression ratios as LZW. 

JPEG Compresses and decompresses with some information loss, but 

can achieve compression ratios anywhere from 10:1 to 100:1. The 
ratio is determined by a user-settable factor ranging from 1.0 to 
255.0, with higher factors yielding greater compression. More 
information is lost with greater compression, but 15:1 
compression is safe for publication quality. Some images can be 
compressed even more. JPEG compression can be used only for 
images that specify at least 4 bits per sample. 

An NXBitmapImageRep can also produce compressed TIFF data for its image using 
any of these schemes. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from NXImageRep 

NXSize 

size; 

Declared in NXBitmapImageRep 

(none) 



METHOD TYPES 

Initializing a new NXBitmapImageRep object 

- initFromSection: 

- initFromFile: 

- initFromStream: 

- initData:fromRect: 

- initData :pixels Wide :pixelsHigh: 

bitsPerSample.samplesPerPixel: 
hasAlpha:isPlanar:colorSpace: 
by tesPerRow: bitsPerPixel: 

- initDataPlanes .‘pixels Wide :pixelsHigh: 

bitsPerSample:samplesPerPixel: 
has Alpha: isPlanar.xolorSpace: 
bytesPerRow: bitsPerPixel: 
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Creating a List of NXBitmapImageReps 

+ newListFromSection: 

+ newListFromSection: zone: 

+ newListFromFile: 

+ newListFromFile:zone: 

+ newListFromStream: 

+ newListFromStream: zone: 

Reading information from a rendered image 

+ sizelmage: 

+ sizeImage:pixelsWide:pixelsHigh: 
bitsPerSample:samplesPerPixel: 
has Alpha: isPlanar: colorSpace: 

Copying and freeing an NXBitmapImageRep 

- copy 

- free 

Getting information about the image 

- bitsPerPixel 

- samplesPerPixel 

- bitsPerS ample (NXImageRep) 

- isPlanar 

- numPlanes 

- numColors (NXImageRep) 

- hasAlpha (NXImageRep) 

- bytesPerPlane 

- bytesPerRow 

- colorSpace 

- pixelsWide (NXImageRep) 

- pixelsHigh (NXImageRep) 

Getting image data - data 

- getDataPlanes: 

Drawing the image - draw 

- drawln: 

- draw At: (NXImageRep) 

Producing a TIFF representation of the image 

- writeTIFF: 

- writeTIFF:usingCompression: 

- writeTIFF:usingCompression:andFactor: 

Archiving - read: 

- write: 
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CLASS METHODS 


newListFromFile: 

+ (List *)newListFromFile:(const char *)filename 

Creates one new NXBitmapImageRep instance for each TIFF image specified in the 
filename file, and returns a List object containing all the objects created. If no 
NXBitmapImageReps can be created (for example, if filename doesn’t exist or doesn’t 
contain TIFF data), nil is returned. The List should be freed when it’s no longer 
needed. 

Each new NXBitmapImageRep is initialized by the initFromFile: method, which 
reads information about the image from filename , but not the image data. The data will 
be read when it’s needed to render the image. 

See also: + newListFromFile:zone:, - initFromFile: 
newListFromFile:zone: 

+ (List *)newListFromFile:(const char *)filename zone:(NXZone *)aZone 

Returns a List of new NXBitmapImageRep instances, just as newListFromFile: does, 
except that the List object and the NXBitmapImageReps are allocated from memory 
located in aZone. 

See also: + newListFromFile:, - initFromFile: 
newListFromSection: 

+ (List *)newListFromSection: (const char *)name 

Creates one new NXBitmapImageRep instance for each TIFF image specified in the 

name section of the_TIFF segment in the executable file, and returns a List object 

containing all the objects created. If not even one NXBitmapImageRep can be created 
(for example, if the name section doesn’t exist or doesn’t contain TIFF data), nil is 
returned. The List should be freed when it’s no longer needed. 

Each new NXBitmapImageRep is initialized by the initFromSection: method, which 
reads information about the image from the section, but doesn’t read image data. The 
data will be read when it’s needed to render the image. 

See also: + newListFromSection:zone:, - initFromSection: 
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newListFromSectionizone: 

+ (List *)newListFromSection: (const char *)name zone:(NXZone *)aZone 

Returns a List of new NXBitmapImageRep instances, just as newListFromSection: 
does, except that the List object and the NXBitmapImageReps are allocated from 
memory located in aZone. 

See also: + newListFromSection:, - initFromSection: 
newListFromStream: 

+ (List *)newListFromStream:(NXStream *)stream 

Creates one new NXBitmapImageRep instance for each TIFF image that can be read 
from stream , and returns a List object containing all the objects created. If not even one 
NXBitmapImageRep can be created (for example, if the stream doesn’t contain TIFF 
data), nil is returned. The List should be freed when it’s no longer needed. 

The data is read and each new object initialized by the initFromStream: method. 

See also: + newListFromStream:zone:, - initFromStream: 

newListFromStream: zone: 

+ (List *)newListFromStream:(NXStream *)stream zone:(NXZone *)aZone 

Returns a List of new NXBitmapImageRep instances, just as newListFromStream: 
does, except that the NXBitmapImageReps and the List object are allocated from 
memory located in aZone. 

See also: + newListFromStream:, - initFromStream: 


sizelmage: 

+ (int)sizelmage: (const NXRect *)rect 

Returns the number of bytes that would be required to hold bitmap data for the rendered 
image bounded by the rect rectangle. The rectangle is located in the current window 
and is specified in the current coordinate system. 

See also: + sizeImage:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel: 
hasAlpha:isPlanar:colorSpace:, - initData:fromRect: 
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sizeImage:pixeIsWide:pixelsHigh:bitsPerSampIe:samplesPerPixel:hasAlpha: 

isPlanartcolorSpace: 

+ (int)sizelmage: (const NXRect *)rect 
pixelsWide:(int *)width 
pixelsHigh:(int *)height 
bitsPerSamp!e:(int *)bps 
samplesPerPixel:(int *)spp 
hasAIpha:(BOOL *)alpha 
isPlanar:(BOOL *)config 
colorSpace:(NXColorSpace *)space 

Returns the number of bytes that would be required to hold bitmap data for the rendered 
image bounded by the rect rectangle. The rectangle is located in the current window 
and is specified in the current coordinate system. 

Every argument but rect is a pointer to a variable where the method will write 
information about the image. For an explanation of the information provided, see the 
description of the initDataPlanes:... method 

See also: - initDataPlanes:pixelsWide:pixelsHigh:bitsPerSample: 
samplesPerPixel: has Alpha: isPIanar: color Space: by tesPer Row: bitsPer Pixel: 

INSTANCE METHODS 

bitsPerPixel 

- (int)bitsPerPixel 

Returns the number of bits allocated for each pixel in each plane of data. This is 
normally equal to the number of bits per sample or, if the data is in meshed 
configuration, the number of bits per sample times the number of samples per pixel. It 
can be explicitly set to another value (in the initData:... or initDataPlanes:. ..method) 
in case extra memory is allocated for each pixel. This may be the case, for example, if 
pixel data is aligned on byte boundaries. 

However, in the current release, an NXBitmapImageRep cannot render an image that 
has empty memory separating pixel specifications. 

bytesPerPlane 

- (int)bytesPerPlane 

Returns the number of bytes in each plane or channel of data. This will be figured from 
the number of bytes per row and the height of the image. 

See also: - bytesPerRow 
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bytesPerRow 

- (int)bytesPerRow 

Returns the minimum number of bytes required to specify a scan line (a single row of 
pixels spanning the width of the image) in each data plane. If not explicitly set to 
another value (in the initData:... or initDataPlanes:... method), this will be figured 
from the width of the image, the number of bits per sample, and, if the data is in a 
meshed configuration, the number of samples per pixel. It can be set to another value 
to indicate that each row of data is aligned on word or other boundaries. 

However, in the current release, an NXBitmapImageRep can’t render an image that has 
empty space at the end of a scan line. 


colorSpace 

- (NXColorSpace)colorSpace 


Returns one of the following enumerated values, which indicate how bitmap data is to 
be interpreted: 


NX_OneIsBlack 
NX_OneIs White 
NX_RGB ColorSpace 
NX_CMYKColorSpace 


A gray scale where 1 means black and 0 means white 
A gray scale where 0 means black and 1 means white 
Red, green, and blue color values 
Cyan, magenta, yellow, and black color values 


These values are defined in the header file appkit/graphics.h. 
See also: - numColors (NXImageRep) 


copy 

-copy 

Returns a new NXBitmapImageRep instance that’s an exact copy of the receiver. The 
new object will have its own copy of the bitmap data, unless the receiver merely 
references the data. In that case, both objects will reference the same data. 

The new object doesn’t need to be initialized. 

data 

- (unsigned char *)data 

Returns a pointer to the bitmap data. If the data is in planar configuration, this pointer 
will be to the first plane. To get separate pointers to each plane, use the getDataPlanes: 
method. 

See also: - getDataPlanes: 
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- (BOOL)draw 


Renders the image at (0.0, 0.0) in the current coordinate system on the current device 
using the appropriate PostScript imaging operator. This method returns YES if 
successful in producing the image, and NO if not. 

See also: - draw At: (NXImageRep), - drawln: 
drawln: 

- (BOOL)drawIn:(const NXRect *)rect 

Renders the image so that it fits inside the rectangle referred to by rect. The current 
coordinate system is translated and scaled so the image will appear at the right location 
and fit within the rectangle. The draw method is then invoked to render the image. 
This method passes through the return value of the draw method, which indicates 
whether the image was successfully drawn. 

The coordinate system is not restored after it has been altered. 

See also: - draw, - draw At: (NXImageRep) 

free 

- free 

Deallocates the NXBitmapImageRep. This method will not free any bitmap data that 
the object merely references—that is, raw data that was passed to it in a initData:... or 
initDataPlanes:... message. 

getDataPlanes: 

- getDataPlanes:(unsigned char **)thePlanes 

Provides bitmap data for the image separated into planes. thePlanes should be an array 
of five character pointers. If the bitmap data is in planar configuration, each pointer will 
be initialized to point to one of the data planes. If there are less than five planes, the 
remaining pointers will be set to NULL. If the bitmap data is in meshed configuration, 
only the first pointer will be initialized; the others will be NULL. Returns self. 

Color components in planar configuration are arranged in the expected order—for 
example, red before green before blue for RGB color. All color planes precede the 
coverage plane. 

See also: - data, - isPlanar 
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init 


Generates an error message. This method cannot be used to initialize an 
NXBitmapImageRep. Instead, use one of the methods listed under “See also” below. 


See also: - initFromSection:, - initFromFile:, - initFromStream:, 

- initDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel: 
has Alpha: isPlanar: color Space: by tesPerRow ibitsPer Pixel:, 

- initData: pixels Wide: pixelsHigh: bitsPer Sample: samplesPerPixel: 
hasAlpha:isPlanar:colorSpace:bytesPerRow:bitsPerPixel:, - initDataifromRect: 

initData:fromRect: 

- initData: (unsigned char *)data fromRect: (const NXRect *)rect 

Initializes the receiver, a newly allocated NXBitmapImageRep object, with bitmap data 
read from a rendered image. The image that’s read is located in the current window and 
is bounded by the rect rectangle as specified in the current coordinate system. 

This method uses PostScript imaging operators to read the image data into the data 
buffer; the object is then created from that data. The object is initialized with 
information about the image obtained from the Window Server. 

If data is NULL, the NXBitmapImageRep will allocate enough memory to hold bitmap 
data for the image. In this case, the buffer will belong to the object and will be freed 
when the object is freed. 

If data is not NULL, you must make sure the buffer is large enough to hold the image 
bitmap. You can determine how large it needs to be by sending a sizelmage: message 
for the same rectangle. The NXBitmapImageRep will only reference the data in the 
buffer; the buffer won’t be freed when the object is freed. 

If for any reason the new object can’t be initialized, this method frees it and returns nil. 
Otherwise, it returns the initialized object (self). 

See also: + sizelmage: 
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i nit Data: pixels Wide: pixelsHigh: bitsPer Sample: samplesPer Pixel: has Alpha: 
isPlanar:colorSpace:bytesPerRow:bitsPerPixel: 

- initData: (unsigned char *)data 
pixels Wide: (mi)width 
pixelsHigh :(int)height 
bitsPerSample: (int)bps 
samplesPerPixel : (int )spp 
has Alpha: (B OOL )alpha 
isPlanar : (B OOL) config 
colorSpace:(NXColorSpace)space 
bytesPerRow: (int )rowBytes 
bitsPerPixel:(int )pixelBits 

Initializes the receiver, a newly allocated NXBitmapImageRep object, so that it can 
render the image specified in data and described by the other arguments. If the object 
can’t be initialized, this method frees it and returns nil. Otherwise, it returns the object 
(self). 

data points to a buffer containing raw bitmap data. If the data is in planar configuration 
(<config is YES), all the planes must follow each other in the same buffer. The 
initDataPlanes:... method can be used instead of this one if there are separate buffers 
for each plane. 

If data is NULL, this method allocates a data buffer large enough to hold the image 
described by the other arguments. You can then obtain a pointer to this buffer (with the 
data or getDataPlanes: method) and fill in the image data. In this case the buffer will 
belong to the object and will be freed when it’s freed. 

If data is not NULL, the object will only reference the image data; it won’t copy it. The 
buffer won’t be freed when the object is freed. 

All the other arguments to this method are the same as those to initDataPlanes:... See 
that method for descriptions. 

See also: - initDataPlanes:pixelsWide:pixelsHigh:bitsPerSample: 
samplesPerPixel:hasAlpha:isPlanar:colorSpace:bytesPerRow:bitsPerPixel: 
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initDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel: 
has Alpha: isPlanar: color Space :by tesPer Row: bitsPer Pixel: 

- initDataPlanes: (unsigned char **)planes 
pixels Wide: (int)vW<ir/i 
pixelsHigh: (int)height 
bitsPer Sample : (int )bps 
samplesPer Pixel: (int)spp 
has Alpha: (BOOL )alpha 
isPlanar: ( BOOL)config 
colorSpace:(NXColorSpac &)space 
bytesPerRow:(int )rowBytes 
bitsPerPixel: (int )pixelB its 

Initializes the receiver, a newly allocated NXBitmapImageRep object, so that it can 
render the image specified in planes and described by the other arguments. If the object 
can’t be initialized, this method frees it and returns nil. Otherwise, it returns the object 
(self). 

planes is an array of character pointers, each of which points to a buffer containing raw 
image data. If the data is in planar configuration, each buffer holds one component— 
one plane—of the data. Color planes are arranged in the standard order—for example, 
red before green before blue for RGB color. All color planes precede the coverage 
plane. 

If the data is in meshed configuration ( config is NO), only the first buffer is read. The 
initData:... method can be used instead of this one for data in meshed configuration. 

If planes is NULL or if it’s an array of NULL pointers, this method allocates enough 
memory to hold the image described by the other arguments. You can then obtain 
pointers to this memory (with the getDataPlanes: or data method) and fill in the image 
data. In this case, the allocated memory will belong to the object and will be freed when 
it’s freed. 

If planes is not NULL and the array contains at least one data pointer, the object will 
only reference the image data; it won’t copy it. The buffers won’t be freed when the 
object is freed. 

Each of the other arguments (besides planes) informs the NXBitmapImageRep object 
about the image. They’re explained below: 

• width and height specify the size of the image in pixels. The size in each direction 
must be greater than 0. 

• bps (bits per sample) is the number of bits used to specify one pixel in a single 
component of the data. All components are assumed to have the same bits per 
sample. 
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• spp (samples per pixel) is the number of data components. It includes both color 
components and the coverage component (alpha), if present. Meaningful values 
range from 1 through 5. An image with cyan, magenta, yellow, and black (CMYK) 
color components plus a coverage component would have an spp of 5; a gray-scale 
image that lacks a coverage component would have an spp of 1. 

• alpha should be YES if one of the components counted in the number of samples 
per pixel (spp) is a coverage component, and NO if there is no coverage component. 

• config should be YES if the data components are laid out in a series of separate 
“planes” or channels (“planar configuration”), and NO if component values are 
interwoven in a single channel (“meshed configuration”). 

For example, in meshed configuration, the red, green, blue, and coverage values for 
the first pixel of an image would precede the red, green, blue, and coverage values 
for the second pixel, and so on. In planar configuration, red values for all the pixels 
in the image would precede all green values, which would precede all blue values, 
which would precede all coverage values. 

• space indicates how data values are to be interpreted. It should be one of the 
following enumerated values (defined in the header file appkit/graphics.h): 


NX_OneIsBlack 
NX_OneIs White 
NX_RGB ColorSpace 
NX_CMYKColorSpace 


A gray scale between 1 (black) and 0 (white) 
A gray scale between 0 (black) and 1 (white) 
Red, green, and blue color values 
Cyan, magenta, yellow, and black color values 


• rowBytes is the number of bytes that are allocated for each scan line in each plane 
of data. A scan line is a single row of pixels spanning the width of the image. 


Normally, rowBytes can be figured from the width of the image, the number of bits 
per pixel in each sample (bps), and, if the data is in a meshed configuration, the 
number of samples per pixel (spp). However, if the data for each row is aligned on 
word or other boundaries, it may have been necessary to allocate more memory for 
each row than there is data to fill it. rowBytes lets the object know whether that’s 
the case. In the current release, an NXBitmapImageRep cannot render an image 
with empty space at the end of a scan line. 

If rowBytes is 0, the NXBitmapImageRep assumes that there’s no empty space at 
the end of a row. 
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• pixelBits informs the NXBitmapImageRep how many bits are actually allocated 
per pixel in each plane of data. If the data is in planar configuration, this normally 
equals bps (bits per sample). If the data is in meshed configuration, it normally 
equals bps times spp (samples per pixel). However, it’s possible for a pixel 
specification to be followed by some meaningless bits (empty space), as may 
happen, for example, if pixel data is aligned on byte boundaries. In the current 
release, an NXBitmapImageRep cannot render an image if this is the case. 

If pixelBits is 0, the object will interpret the number of bits per pixel to be the 
expected value, without any meaningless bits. 

This method is the designated initializer for NXBitmapImageReps that handle raw 
image data. 

See also: - initData:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixeI: 
hasAlpha:isPlanar:colorSpace:bytesPerRow:bitsPerPixel: 

initFromFile: 

- initFromFile: (const char *)filename 

Initializes the receiver, a newly allocated NXBitmapImageRep object, with the TIFF 
image found in the filename file. This method reads some information about the image 
from filename, but not the image itself. Image data will be read when it’s needed to 
render the image. 

If the new object can’t be initialized for any reason (for example, filename doesn’t exist 
or doesn’t contain TIFF data), this method frees it and returns nil. Otherwise, it returns 
self. 

This method is the designated initializer for NXBitmapImageReps that read image data 
from a file. 

See also: + newListFromFile:, - initFromSection: 
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initFromSection: 


- initFromSection ’.(const char *)name 

Initializes the receiver, a newly allocated NXBitmapImageRep object, with the TIFF 

image found in the name section in the_TIFF segment of the application executable. 

This method reads some information about the image from the section, but not the 
image itself. Image data is read only when it’s needed to render the image. 

If the new object can’t be initialized for any reason (for example, the name section 
doesn’t exist or doesn’t contain TIFF data), this method frees it and returns nil. 
Otherwise, it returns self. 

This method is the designated initializer for NXBitmapImageReps that read image data 
from a section of the_TIFF segment. 

See also: + newListFromSection:, - initFromFile: 


initFromStream: 

- initFromStream: (NXStream *)stream 

Initializes the receiver, a newly allocated NXBitmapImageRep object, with the TIFF 
image read from stream. If the new object can’t be initialized for any reason (for 
example, stream doesn’t contain TIFF data), this method frees it and returns nil. 
Otherwise, it returns self. 

This method is the designated initializer for NXBitmapImageReps that read image data 
from a stream. 

See also: + newListFromStream: 

isPlanar 

- (BOOL)isPlanar 

Returns YES if image data is segregated into a separate plane for each color and 
coverage component (planar configuration), and NO if the data is integrated into a 
single plane (meshed configuration). 

See also: - sampIesPerPixel 
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numPlanes 


- (int)numPlanes 

Returns the number of separate planes that image data is organized into. This will be 
the number of samples per pixel if the data has a separate plane for each component 
(isPlanar returns YES) and 1 if the data is meshed (isPlanar returns NO). 

See also: - isPlanar, - samplesPerPixel, - hasAlpha, - numColors (NXImageRep) 
read: 

- read:(NXTypedStream *)stream 

Reads the NXBitmapImageRep from the typed stream stream. 

See also: - write: 

samplesPerPixel 

- (int)samplesPerPixel 

Returns the number of components in the data. It includes both color components and 
the coverage component, if present. 

See also: - hasAlpha, - numColors (NXImageRep) 

write: 

- write :(NXTypedStream *)stream 

Writes the NXBitmapImageRep to the typed stream stream. 

See also: - read: 

writeTIFF: 

- writeTIFF:(NXStream *)stream 

Writes a TIFF representation of the image to stream. This method is equivalent to 

writeTIFF:usingCompression:andFactor: when 

NX_TIFF_COMPRESSION_NONE is passed as the second argument. The TIFF data 
is not compressed. 

See also: - writeTIFF:usingCompression:andFactor: 
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writeTIFF: usingCompr ession: 

- writeTIFF :(NXStream *)stream usingCompression : (mt)compression 

Writes a TIFF representation of the image to stream , compressing the data according 
to the compression scheme. This method is equivalent to 

writeTIFF:usingCompression:andFactor: when 0.0 is passed as the third argument. 
If compression is NX_TIFF_COMPRESSION_JPEG, the default compression factor 
will be used. This and the other compression constants are listed under the next 
method. 

See also: - writeTIFF:usingCompression:andFactor: 

writeTIFF:usingCompression:andFactor: 

- writeTIFF :(NXStream *)stream 

usingCompression: (int)compression 
andFactor: (f[oat)factor 

Writes a TIFF representation of the image to stream. If the stream isn’t currently 
positioned at location 0, this method assumes that it contains another TIFF image. It 
will try to append the TIFF representation it writes to that image. To do this, it must 
read the header of the image already in the stream. Therefore, the stream must be 
opened with NX_READWRITE permission. 

The second argument, compression , indicates whether or not the data should be 
compressed and, if so, which compression scheme to use. It should be one of the 
following constants: 

NX_TIFF_COMPRESSION_LZW LZW compression 

NX_TIFF_COMPRESSION_PACKBITS PackBits compression 

NX_TIFF_COMPRESSION_JPEG JPEG compression 

NX_TIFF_COMPRESSION_NONE No compression 

The third argument, factor, is used in the JPEG scheme to determine the degree of 
compression. If factor is 0.0, the default compression factor of 10.0 will be used. 
Otherwise, factor should fall within the range 1.0-255.0, with higher values yielding 
greater compression but also greater information loss. 

The compression schemes are discussed briefly under “CLASS DESCRIPTION” 
above. 
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NXBrowser 


INHERITS FROM Control: View : Responder : Object 

DECLARED IN appkit/NXBrowser.h 


CLASS DESCRIPTION 

NXBrowser provides a user interface for displaying and selecting hierarchically 
organized data such as directory paths. The levels of the hierarchy are displayed in 
columns. Columns are numbered from left to right, beginning with 0. Each column 
consists of a Scroll View or Clip View containing a Matrix filled with NXBrowserCells. 
NXBrowser must have a delegate; the delegate’s role is to provide the data that fills the 
columns as the user navigates through the hierarchy. 

You can implement one of three delegate types—normal, lazy, or very-lazy— 
depending on your needs for performance and memory use. A normal delegate 
implements the browser:fillMatrix:inColumii: method; implemented alone, this 
method may improve performance if the data space is small, since it always creates and 
loads all the entries in a column. A lazy delegate implements the 
browser:fillMatrix:mCohimn: and browser:loadCell:atRow:inCoIumn: methods; 
lazy delegates create all cells in a column, but they load only those that are displayed. 
A very-lazy delegate implements the browser;loadCell:atRow:inColumn: and 
browser:getNumRowsInColumn: methods. Very-lazy delegates make spare use of 
memory by not creating a cell for an entry until it’s to be displayed; this is useful for 
large, potentially open-ended data spaces. A delegate must implement either the 
normal, lazy, or very-lazy methods; however, it shouldn’t implement both the 
browser:fillMatrix:inColumn: and browserigetNumRowsInColumn: methods. 

An entry in NXBrowser’s columns can be either a branch node (such as a directory) or 
a leaf node (such as a file). As the delegate loads an entry in a Cell, it invokes 
NXBrowserCell’s setLeaf: method to specify the type of entry. When the user selects 
a single branch node entry in a column, the NXBrowser sends itself the addColumn 
message, which messages the delegate to load the next column. NXBrowser can be set 
to allow selection of multiple entries in a column, or to limit selection to a single entry. 
When set for multiple selection, it can also be set to limit multiple selection to leaf 
nodes only, or to allow selection of both types of nodes together. 

As a subclass of Control, NXBrowser has a target object and action message. Each 
time the user selects one or more entries in a column, the action message is sent to the 
target. 

You can change the appearance and user interface features of NXBrowser in a number 
of ways. Columns in the NXBrowser may have up and down scroll buttons, scroll bars, 
both, or neither. The NXBrowser itself may or may not have left and right scroll 
buttons. You generally won’t create NXBrowser without scrollers; if you do, you must 
make sure the bounds rectangle of the NXBrowser is large enough that all its rows and 
columns can be displayed. The NXBrowser’s columns may be bordered and titled, 
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bordered and untitled, or unbordered and untitled. A column’s title may be taken from 
the selected entry in the column to its left, or may be provided explicitly by NXBrowser 
or its delegate. 

You can drag NXBrowser into an application from the Interface Builder Palettes panel. 
Interface Builder provides easier ways to set many of the user interface features 
described previously. 

INSTANCE VARIABLES 



Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

NXRect 

id 

id 

id 

struct_vFlags 

frame; 

bounds; 

superview; 

subviews; 

window; 

vFlags; 

Inherited from Control 

int 

id 

struct _conFlags 

tag; 

cell; 

conFlags; 

Defined in NXBrowser 

id 

id 

SEL 

SEL 

id 

id 

unsigned short 

target; 

delegate; 

action; 

doubleAction; 

matrixClass; 

cellPrototype; 

pathSeparator; 

target 

The object notified by NXBrowser when one or 
more items are selected in a column. 

delegate 

The object providing the data which is browsed 
by the NXBrowser. 

action 

The message sent to the target when one or more 
entries are selected in a column. 

doubleAction 

The message sent to the target when an entry in 
the NXBrowser is double-clicked. 

matrixClass 

The class used to instantiate the matrices in the 
columns of NXBrowser; Matrix by default. 

pathSeparator 

The character which separates the substrings of a 
path (see getPathiToColumn:, setPath:). 
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METHOD TYPES 


Initializing and freeing 
Setting the delegate 
Setting target and action 


Setting the Matrix class 
Setting the Cell class 

Setting NXBrowser behavior 


Setting NXBrowser appearance 


- initFrame: 

- free 

- delegate 

- setDelegate: 

- action 

- setAction: 

- target 

- setTarget: 

~ doubleAction 

- setDoubleAction: 

- setMatrixClass: 

- setCellClass: 

- cellPrototype 

- setCellPrototype: 

- allowMultiSel: 

- allowBranchSel: 

- reuseColumns: 

- acceptArrowKeys: 

- acceptsFirstResponder 

- setEnabled: 

- hideLeftAndRightScrollButtons: 

- useScrollButtons: 

- useScrollBars: 

- setMinColumnWidth: 

- minColumnWidth 

- setMaxVisibleColumns: 

- maxVisibleColumns 

- numVisibleColumns 

- firstVisibleColumn 

- lastVisibleColumn 

- lastColumn 

- separateColumns: 

- columnsAreSeparated 
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Manipulating columns 

- loadColumnZero 

- isLoaded 

- addColumn 

- reloadColumn: 

- displayColumn: 

- displayAllColumns 

- setLastColumn: 

- select All: 

- selectedColumn 

- columnOf: 

- validateVisibleColumns 

Manipulating column titles 

- getTitleFromPreviousColumn: 

- isTitled 

- setTitled: 

- getTitleFrame:ofColumn: 

- setTitle:ofColumn: 

- drawTitle:inRect:ofColumn: 

- clearTitleInRect:ofColumn: 

- titleHeight 

- titleOfColumn: 

Scrolling the NXBrowser 

- scrollColumnsRightBy: 

- scrollColumnsLeftBy: 

- scrollColumnToVisible: 

- scrollUpOrDown: 

- reflectScroll: 

Event handling 

- mouseDown: 

- keyDown: 

- doClick: 

- doDoubleClick: 

Getting column Matrices and Cells 

- getLoadedCellAtRow:inColumn: 

- matrixInColumn: 

Getting column frames 

- getFrame:ofColumn: 

- getFrame:ofInsideOfColumn: 

Paths 

- setPathSeparator: 

- setPath: 

- getPath:toColumn: 

Drawing 

- drawS elf:: 

Resizing the NXBrowser 

- sizeTo:: 

- sizeToFit 

Arranging NXBrowser components 

- tile 
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INSTANCE METHODS * 


acceptArrowKeys: 

- acceptArrowKeys: (BOOL)flag 

Sets NXBrowser handling of arrow key input. If flag is YES, then the keyboard arrow 
keys move the selection whenever the NXBrowser or one of its subviews is the first 
responder; if flag is NO, arrow key input has no effect. Returns self. 

acceptsFirstResponder 

- (BOOL)acceptsFirstResponder 

Returns YES if the NXBrowser accepts arrow key input; NO otherwise. The default 
setting is NO. 

See also: - acceptArrowKeys: 
action 

- (SEL)action 

Returns the action sent to the target by the NXBrowser when the user makes a selection 
in one of its columns. 

See also: - doubleAction, - setAction:, - setDoubleAction: 

addColumn 

- addColumn 

Adds a column to the right of the last column in the NXBrowser and, if necessary, 
scrolls the NXBrowser so that the new column is visible. You never invoke this 
method; it’s invoked by doClick: and keyDown: when the user selects a single branch 
node entry in the NXBrowser, and by setPath: when it matches a path substring with a 
branch node entry. Returns self. 

See also: - loadColumnZero, - reloadColumn:, - setPath: 

allowBranchSel: 

- allowBranchSel:(BOOL)//ag 

Sets whether the user can select multiple branch and leaf node entries. If flag is YES 
and multiple selection is enabled (by allowMultiSel:), then multiple branch and leaf 
node entries can be selected. By default, a user can choose only multiple leaf node 
entries when multiple entry selection is enabled. Returns self. 

See also: - allowMultiSel: 
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allowMultiSel: 

- aIIowMuItiSel:(BOOL)/#g 

Sets whether the user can select multiple entries in a column. If flag is YES, the user 
can choose any number of leaf entries in a column (or leaf and branch entries if enabled 
by allowBranchSel:). By default, the user can choose just one entry in a column at a 
time. Returns self. 

See also: -allowBranchSel: 

cellPrototype 

- cellPrototype 

Returns the NXBrowser’s prototype cell. This cell is copied to create new cells in the 
columns of the NXBrowser. 

See also: - setCellPrototype: 
clearTitlelnRect: of Column: 

- clearTitlelnRect: (const NXRect *)aRect ofCoIumn:(int)co/«m« 

Clears the title displayed in aRect above column. You don’t invoke this method 
directly; it’s called whenever a title of a column needs to be cleared. You can override 
this method if you draw your own column titles. aRect is in the NXBrowser’s 
coordinate system. Returns self. 

columnOf: 

- (int)columnOf:m<2rra: 

Returns the index of the column containing matrix', the leftmost (root) column is 0. 
Returns -1 if no column contains matrix. 

See also: - matrixInColumn: 

columnsAreSeparated 

- (BOOL)coIumnsAreSeparated 

Returns YES if columns are separated by a bezeled bar; NO otherwise. If the 
NXBrowser is set to display column titles, its columns are automatically separated by 
bezels; however, the value returned by this method is not changed by the setTitled: 
method. 

See also: - separateColumns:, - setTitled: 
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delegate 

- delegate 

Returns the delegate of the NXBrowser, the object that provides the data to be browsed. 
See also: - setDelegate:, “METHODS IMPLEMENTED BY THE DELEGATE” 

display AllColumns 

- display AllColumns 

Causes columns currently visible in the NXBrowser to be redisplayed. You can call this 
to update the NXBrowser after manipulating it with display disabled in the window. 
Returns self. 

displayColumn: 

- displayColumn :(int)column 

Validates and displays column number column. You can call this method to update the 
NXBrowser after manipulating it with display disabled in column. Returns self. 

See also: - display AllColumns 

doClick: 

- doClickrsender 

You never invoke this method. This is the action message sent to the NXBrowser by a 
column’s Matrix when a mouse-down event occurs in a column. It sets the lastColumn 
to that of the Matrix where the click occurred, and removes any columns to the right 
that were previously loaded in the NXBrowser. If a single branch node entry is selected 
by the event, this method sends addColumn to self to display the corresponding data 
in the column to the right. It sends the NXBrowser’s action message to its target and 
returns self. 

See also: - action, - setAction, - setTarget, - target 

doDoubleClick: 

- doDoubleClick:serafer 

You never invoke this method. This is the action message sent to the NXBrowser by a 
column’s Matrix when a double-click occurs in a column. This method simply sends 
the doubleAction message to the target; if no doubleAction message is set, it sends the 
action. Override this method to add specific behavior for double-click events. Returns 
self. 

See also: - doubleAction, - setDoubleAction, - setTarget, - target 
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doubleAction 

- (SEL)doubleAction 

Returns the action sent by the NXBrowser to its target when the user double-clicks on 
an entry. If no doubleAction message is specified, this method returns the action. 

See also: - setDoubleAction: 
drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

Draws the NXBrowser; loads column 0 if it has not been loaded. Override this method 
if you change the way NXBrowser draws itself. You never invoke this method; it’s 
invoked by the display method. Returns self. 

drawTitle:inRect:ofColumn: 

- drawTitle: (const char *)title 

inRect: (const NXRect *)aRect 
ofColumn:(int )column 

You never invoke this method. It’s invoked whenever the NXBrowser needs to draw a 
column title. You may override it if you draw your own column titles. Returns self. 

firstVisibleColumn 

- (int)firstVisibleColumn 

Returns the index of the leftmost visible column. 

See also: - lastVisibleColumn 

free 

- free 

Frees the NXBrowser and all the objects it manages: scrollviews, matrices, cells, scroll 
buttons, prototypes, and so on. Returns nil. 

getFrame:ofColumn: 

- (NXRect *)getFrame: (NXRect *)theRect ofInsideOfColumn:(int)c0/wrarc 

Returns a pointer to the rectangle (in NXBrowser coordinates) containing column', the 
pointer is returned both explicitly by the method and implicitly in theRect, The 
returned rectangle includes the bezel area surrounding the column. If column isn’t 
currently loaded or displayed, this method returns NULL explicitly, without changing 
the coordinates of the rectangle represented in theRect. It also returns NULL if theRect 
is NULL. 
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getFrame loflnsideOfColumn: 

- (NXRect *)getFrame: (NXRect *)theRect ofInsideOfColumn:(int)co/Mm« 

Returns a pointer to the rectangle (in NXBrowser coordinates) containing the “insides” 
of column’, the pointer is returned both explicitly by the method and implicitly in 
theRect. The “insides” are defined as the area in the column that contains the cells and 
only that area (i.e., no bezels). If column isn’t currently loaded or displayed, this 
method returns NULL explicitly, without changing the coordinates of the rectangle 
represented in theRect. It also returns NULL if theRect is NULL. 

getLoadedCellAtRow:inColumn: 

- getLoadedCellAtRow:(int)row inColumn:(int )column 

Returns the cell at row in column, if that column is currently in the NXBrowser. This 
method creates and loads the cell if necessary. It’s the safest way to get a particular cell 
in a column, since lazy delegates don’t load every cell in a matrix and very-lazy 
delegates don’t even create all cells until they’re displayed. This method is preferred 
to the Matrix method cellAt::. If the specified column isn’t in the NXBrowser, or if row 
doesn’t exist in column, returns nil. 

getPathitoColumn: 

- (char *)getPath:(char *)thePath toColumn:(int)co/wmw 

Returns a pointer to the string representing the path to column, both explicitly and in 
thePath. Before invoking this method, you must allocate sufficient memory to accept 
the entire path string, and set thePath as a pointer to that memory, column must 
currently be loaded in the NXBrowser. If column isn’t loaded or thePath is a null 
pointer, this method returns NULL. 

The path is constructed by concatenating the string values in the selected cells in each 
column, preceding each with the pathSeparator. For example, consider a pathSeparator 
and an NXBrowser with two columns. If the selected cell in the left column has 
the string value “foo” and the selected cell in the right column has the string value “bar,” 
the resulting path is “@foo@bar.” The default pathSeparator is the slash character 

(T). 


See also: - pathSeparator, - setPath:, - setPathSeparator: 

getTitleFrame: of Column: 

- (NXRect *)getTitleFrame: (NXRect *)theRect ofColumn : (mt)column 

Returns theRect, a pointer to the rectangle (in NXBrowser coordinates) enclosing the 
title of column number column. If the NXBrowser isn’t displaying titles or the 
specified column isn’t loaded, returns NULL. 
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getTitleFromPreviousColumn: 

- getTitleFromPreviousColumn : (B QQL)flag 

If flag is YES, sets the NXBrowser so that each column takes its title from the string 
value in the selected cell in the column to its left, leaving column 0 untitled; use 
setTitle:ofColumn: to give column 0 a title. This method affects the receiver only 
when it is titled (isTitled returns YES). 

By default, the NXBrowser is set to get column titles from the previous column. Send 
this message with NO as the argument if your delegate implements the 
browser JtitleOfColumn: method or if you use the setTitlerofColumn: method to 
set all column titles. Returns self. 

See also: - isTitled, - setTitletofColumn:, - setTitled:, - browserrtitleOfColumn: 
in “METHODS IMPLEMENTED BY THE DELEGATE” 

hideLeft AndRightScroIIButtons: 

- hideLeftAndRightScrollButtons:(BOOL)j^ag 

If flag is YES, sets the NXBrowser to hide left and right scroll buttons. Generally, you 
shouldn’t hide left and right scroll buttons unless your data is nonhierarchical, thus 
limited to a single column, or restricted so that the NXBrowser will always display 
enough columns for all data. Returns self. 

initFrame 

- initFrame: (const NXRect *)frameRect 

Initializes a new instance of NXBrowser with a bounds of frameRect. The initialized 
NXBrowser is set to have column titles, to get titles from previous columns, and to use 
scrollbars. The minimum column width is set to 100 and the path separator is set to the 
slash (“/”) character. The NXBrowser is set not to clip. This method invokes the tile 
method to arrange the components of the NXBrowser (titles, scroll bars, matrices, and 
so on). 

isLoaded 

- (BOOL)isLoaded 

Returns YES if any of the NXBrowser’s columns are loaded. 

See also: loadColumnZero 
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isTitled 


- (BOOL)isTitled 

Returns YES if the NXBrowser’s columns are displayed with titles above them; NO 
otherwise. 

See also: - getTitleFromPreviousColumn:, - setTitled: 
keyDown 

- keyDown :(NXEvent *)theEvent 

Handles arrow key events. This method is invoked when the NXBrowser or one of its 
subviews is the first responder. If the NXBrowser has been set to accept arrow keys, 
and the key represented in theEvent is an arrow key, this method scrolls through the 
NXBrowser in the direction indicated. 

See also: - acceptArrowKeys:, - acceptsFirstResponder 

last Y isibleColumn 

- (int)lastVisibleColumn 

Returns the index of the rightmost visible column. This may be less than the value 
returned by lastColumn if the NXBrowser has been scrolled left. 

See also: - firstVisibleColumn, - lastColumn 

lastColumn 

- (int)lastColumn 

Returns the index of the last column in the NXBrowser. 

loadColumnZero 

- loadColumnZero 

Loads and displays data in column 0 of the NXBrowser, unloading any columns to the 
right that were previously loaded. Invoke this method to force the NXBrowser to be 
loaded. You may want to override this method if you subclass NXBrowser. 

See also: - addColumn, - reloadColumn: 

matrixInColumn: 

- matrixInColumn :{mi)column 

Returns the matrix found in column number column. Returns nil if column number 
column isn’t loaded in the NXBrowser. 
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maxVisibleColumns 

- (int)maxVisibleColumns 

Returns the maximum number of visible columns allowed. No matter how many 
loaded columns the NXBrowser contains, or how large the NXBrowser is made (for 
example, by resizing its window), it will never display more than this number of 
columns. If the number of loaded columns can exceed the value returned by this 
method, the NXBrowser must display left and right scroll buttons. 

See also: - hideLeftAndRightScrolIButtons, - setMaxVisibleColumns 

minColumnWidth 

- (int)minColumn Width 

Returns the minimum width of a column in PostScript points (rounded to the nearest 
integer). No column will be smaller than the returned value unless the NXBrowser 
itself is smaller than that. The default setting is 100 points. 

See also: - setMinColumnWidth 
mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Handles a mouse down in the NXBrowser’s left or right scroll buttons. Returns self. 

numVisibleColumns 

- (int)numVisibleColumns 

Returns the number of columns which can be visible at the same time in the 
NXBrowser (that is, the current width, in columns, of the NXBrowser). This may be 
less than the value returned by maxVisibleColumns if the window containing the 
NXBrowser has been resized. 

See also: - setMaxVisibleColumns 

reflectScroIl: 

- reflectScrolhc/jpVz'ew 

This method updates scroll bars in the column containing clipView. Scroll bars are 
enabled if a column contains more data than can be displayed at once and disabled if 
the column can display all data. Returns self. 

See also: - useScrollBars 
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reload Column: 


- reloadColumn:(int )column 

Reloads column number column by sending a message to the delegate to update the 
Cells in its Matrix, then reselecting the previously selected Cell if it’s still in the Matrix. 
Redraws the column and returns self. 

reuseColumns: 

- reuseColumns:(BOOL)y7<2g 

Sets whether the NXBrowser saves a column’s Matrix and Clip View or Scroll View 
when the column is removed, and whether it then reuses these subviews when the 
column is reloaded. If flag is YES, the NXBrowser reuses columns for somewhat faster 
display of columns as they are reloaded. If flag is NO, the NXBrowser frees columns 
as they’re unloaded, reducing average memory use. Returns self. 

scrollColumnsLeftBy: 

- scrollColumnsLeftBy: ( int)shiftAmount 

Scrolls the NXBrowser left (toward the first column) by shiftAmount columns. If 
shiftAmount exceeds the number of columns to the left of the first visible column, then 
the NXBrowser scrolls left until the column 0 is visible. Redraws and returns self. 

See also: - scrolIColumnsRightBy: 

scrollColumnsRightBy: 

- scrollColumnsRightBy: (int)shiftAmount 

Scrolls the NXBrowser right (toward the last column) by shiftAmount columns. If 
shiftAmount exceeds the number of loaded columns to the right of the first visible 
column, then the NXBrowser scrolls right until the last loaded column is visible. 
Redraws and returns self. 

See also: - scrollColumnsLeftBy: 

scrollColumnT oVisible: 

- scrollColumnTo Visible : (int )column 

Scrolls the NXBrowser to make column number column visible. If there’s no column 
in the NXBrowser, this method scrolls to the right as far as possible. Redraws and 
returns self. 
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scrollUpOrDown: 

- scrollUpOrDown ’.sender 

Scrolls a column up or down. You don’t send this message; NXBrowser receives it 
from a column’s scroll buttons. Returns self. 

selectedColumn 

- (int)selectedColumn 

Returns the column number of the rightmost column containing a selected cell. 
Returns -1 if no column in the NXBrowser contains a selected cell. 

selectAll 

- select A\\: sender 

Selects all entries in the last column loaded in the NXBrowser if multiple selection is 
allowed. Returns self. 

See also: - allowMultiSel: 

separateColumns: 

- separateColumns: (BOOL)flag 

If flag is YES, sets NXBrowser so that columns have bezeled borders separating them; 
if NO, the borders are removed. When titles are set to display (by setTitled:), columns 
are automatically separated; however, the flag set by this method is unchanged. 
Redraws the NXBrowser and returns self. 

See also: - setTitled: 
set Action: 

- setAction:(SEL)tfSWecfor 

Sets the action of the NXBrowser. aSelector is the selector for the message sent to the 
NXBrowser’s target when a mouse-down event occurs in a column of the NXBrowser. 
Returns self. 

See also: - action, - doubleAction, - doClick, - doDoubleClick, - setTarget, 

- target 
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setCellClass: 


- setCellClass iclassld 

Sets the class of Cell used when adding Cells to a Matrix in a column of the 
NXBrowser. classld must be the value returned when sending the class message to 
NXBrowserCell or a subclass of NXBrowserCell. Returns self. 

See also: - cellClass, - setCellPrototype 

setCellPr ototy pe: 

- setCellPrototyp tiaCell 

Sets aCell as the Cell prototype copied when adding Cells to the Matrices in the 
columns of NXBrowser. aCell must be an instance of NXBrowserCell or a subclass of 
NXBrowserCell. Returns self. 

See also: - cellPrototype 

setDelegate: 

- setDelegat e:anObject 

Sets the delegate of the NXBrowser to anObject and returns self. If anObject is of a 
class that implements the browser:fillMatrix:inColumn: method (normal or lazy 
delegates) or the browser:loadCell:atRow:inColumn and 
browser:getNumRowsInColumn: methods (very lazy delegate), it’s set as the 
NXBrowser’s delegate; otherwise, the delegate is set to nil. Returns self. 

See also: - delegate, “METHODS IMPLEMENTED BY THE DELEGATE” 

setDouble Action: 

- setDouble Action: (SEL)aSelector 

Sets the double action of the NXBrowser. aSelector is the selector for the action 
message sent to the target when a double-click occurs in one of the columns of the 
NXBrowser. Returns self. 

setEnabled: 

- setEnabled: (BOOL)flag 

Enables the NXBrowser when flag is YES; disables it when flag is NO. Returns self. 
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setLastColumn: 


- setLastColumn :(int)column 

Sets the last column loaded in and displayed by the NXBrowser. Removes any columns 
to the right of column from the NXBrowser. Scrolls columns in the NXBrowser to 
make the new last column visible if it wasn’t previously. If column is to the right of the 
last column in the NXBrowser, this method does nothing. Returns self. 

setMatrixClass: 

- setMatrixClasstc/ow/d 

Sets the matrixClass instance variable, representing the class used when adding new 
columns to the NXBrowser. classld must be the value returned by sending the class 
message to Matrix or a subclass of Matrix; otherwise this method retains the previous 
setting for matrixClass. Returns self. 

setMax VisibleColumns: 

- setMaxVisibleColumns:(int)co/Mm«C<9M«r 

Sets the maximum number of columns that may be displayed by the NXBrowser. 
Returns self. 

To set the number of columns displayed in a new NXBrowser, first send it a 
setMinColumnWidth; message with a small argument (1 for example) to ensure that 
the desired number of columns will fit in the NXBrowser’s frame. Then invoke this 
method to set the number of columns you want your NXBrowser to display. 

See also: - max VisibleColumns, - setMinColumn Width; 

setMinColumnWidth; 

- setMinColumnWidth: (int )columnWidth 

Sets the minimum width for each column to columnWidth and redisplays the 
NXBrowser with columns set to the new width. columnWidth is measured in PostScript 
points rounded to the nearest integer. The default setting is 100. Returns self. 

See also: - minColumnWidth 


2-338 Chapter 2: Class Specifications 



setPath: 


- setPath: (const char *)path 

Parses aPath —a string consisting of one or more substrings separated by the path 
separator—and selects column entries in the NXBrowser that match the substrings. If 
the first character in aPath is the path separator, this method begins searching for 
matches in column 0; otherwise, it begins searching in the last column loaded. If no 
column is loaded, this method loads column 0 and begins the search there. While 
parsing the current substring, it tries to locate a matching entry in the search column. 
If it finds an exact match, this method selects that entry and moves to the next column 
(loading the column if necessary) to search for the next substring. 

If this method finds a valid path (one in which each substring is matched by an entry in 
the corresponding column), it returns self. If it doesn’t find an exact match on a 
substring, it stops parsing aPath and returns nil; however, column entries that it has 
already selected remain selected. 

See also: - getPathrtoColumn, - pathSeparator, - setPathSeparator 
setPathSeparator: 

- setPathSeparator: (unsigned short)charCode 

Sets the character used as the path separator; the default is the slash character (“/”). 
Returns self. 

See also: - getPathrtoColumn, - pathSeparator, - setPath: 

setTarget: 

- setTarget :anObject 

Sets the target of the NXBrowser. Returns self. 
setTitle:ofColumn: 

- setTitle: (const char *)aString ofCo\umn:(int)column 

Sets the title of column number column in the NXBrowser to aString. Returns self. 

See also: - browser:TitleOfColumn: in “METHODS IMPLEMENTED BY THE 
DELEGATE,” - getTitleFromPreviousColumn:, and - setTitled: 
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setTitled: 


- setTitled :(BOOL)flag 

If flag is YES, columns display titles and are separated by bezeled borders. Returns 
self. 

See also: - browser:Tit!eOfColumn: in “METHODS IMPLEMENTED BY THE 
DELEGATE,” - getTitleFromPreviousColumn:, and - setTitleiofColumn: 

sizeTo:: 

- sizeTo : (NXC ooxd)width : (NXCoord)height 

Resizes the NXBrowser to the new width and height. Usually sent by the window. 
Returns self. 


sizeToFit 

- sizeToFit 

Resizes the NXBrowser to contain all the columns and controls displayed in it. Returns 
self. 

target 

- target 

Returns the target for the NXBrowser’s action message. 

See also: - action, - doClick, - doDoubleClick, - doubleAction, - setAction, 

- setDoubleAction, - setTarget: 


tile 

- tile 

Arranges the various subviews of NXBrowser—scrollers, columns, titles, and so on— 
without redrawing. You shouldn’t send this message. Rather, it’s invoked any time the 
appearance of the NXBrowser changes; for example, when scroll buttons or scroll bars 
are set, a column is added, and so on. Override this method if you change the 
appearance of the NXBrowser, for example, if you draw your own titles above columns. 
Returns self. 

titleHeight 

- (NXCoord)titleHeight 

Returns the height of titles drawn above the columns of the NXBrowser. Override this 
method if you display your own titles above the NXBrowser’s columns. 
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titleOfColumn: 


- (const char *)titleOfColumn:(int)cc>/www 

Returns a pointer to the title string displayed above column number column. If no such 
column is loaded in the NXBrowser, returns NULL. 

useScrollBars: 

- useScrollBars: (BOOL )flag 

If flag is YES, sets NXBrowser to use scroll bars for its columns. By default, 
NXBrowser does use scroll bars. Redraws and returns self. 

See also: - useScrollButtons 

useScrollButtons: 

- useScrollButtons: (BOOL)flag 

If flag is YES, sets the NXBrowser to use scroll buttons for its columns. When the 
NXBrowser is also set to use scroll bars, this method causes scroll buttons to display at 
the base of the scroll bars. Redraws and returns self. 

See also: - useScrollBars 

validateVisibleColumns 

- validateVisibleColumns 

Validates the columns visible in the NXBrowser by invoking the delegate method 
browser:columnIsValid: for all visible columns. Use this method to confirm that the 
entries displayed in each visible column are valid before redrawing. 

See also: browser:columnIsValid in “METHODS IMPLEMENTED BY THE 
DELEGATE” 


METHODS IMPLEMENTED BY THE DELEGATE 

browser: columnls V alid: 

- (BOOL)browser '.sender columnIsVaIid:(int)a?/wm« 

This method is invoked by NXBrowser’s validateVisibleColumns method to 
determine whether the contents currently loaded in column number column need to be 
updated. Returns YES if the contents are valid; NO otherwise. 
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bro wserDidScroll: 

- browserDidScroll:,s£«der 

Notifies the delegate when the browser has finished scrolling. Returns self. 

browser:flllMatrix:mColumn: 

- (int)browser: sender 

fillMatrix: matrix 
inColumn:(int)c<9/«m/2 

Invoked by the NXBrowser to query a normal or lazy browser for the contents of 
column. This method should create NXBrowserCells by sending addRow or 
insertRowAt: messages to matrix. A normal delegate should then load each new 
NXBrowserCell and send them the messages setLoaded: and setLeaf:. A lazy 
delegate loads Cells only when they are about to be displayed. This method returns the 
number of entries in column. 

If you implement this method, don’t implement the delegate method 
browser :getNumRowsInColumn:. 

browser:getNumRowsInColumn: 

- (int)browser: sender getNumRowsInCoIumn:(int)c<9/«w/? 

Implemented by very-lazy delegates, this method is invoked by the NXBrowser to ask 
the delegate for the number of rows in column number column. This method allows the 
NXBrowser to resize its scroll bar for a column, without loading all the cells in that 
column. Returns the number of rows in column. 

If you implement this method, don’t implement the delegate method 

browser:fillMatrix:inColumn:. 


browser: loadCell: atRow: inColumn: 

- browser '.sender 

loadCell icell 
atRow: (int)raw 
inColumn: (int )column 

Implemented by lazy and very-lazy delegates. This method loads the entry in cell in 
the specified row and column in the NXBrowser. This method should send setLoaded: 
and setLeaf: messages to cell. Returns self (the id of the delegate). 
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browser: selectCell: inColumn: 

- (BOOL)browser ‘.sender 

selectCell: (const char *)entry 
inColumn :(int )column 

Asks NXBrowser’s delegate to validate and select an entry in column number column. 
This method should load entry if necessary and send it setLoaded: and setLeaf: 
messages to indicate its state. Returns YES if the method successfully selects entry in 
column ; NO otherwise. 

browser:titleOfColumn: 

- (const char *)browser '.sender titleOfColumn:(int )column 

Invoked by NXBrowser to get the title for column from the delegate. This method is 
invoked only when the NXBrowser is titled and has received a 
getTitleFromPreviousColumn: message with NO as the argument. By default, the 
NXBrowser makes each column title the string value of the selected cell in the previous 
column. Returns the string representing the title belonging above column. 

See also: - getTitledFromPreviousColumn:, - setTitlerofColumn:, - setTitled: 

browserWillScroll: 

- browserWillScroll render 

This method notifies the delegate when the browser is about to scroll. Returns self. 
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NXBrowserCell 


INHERITS FROM Cell: Object 

DECLARED IN appkit/NXBrowserCell.h 

CLASS DESCRIPTION 

NXBrowserCell is the subclass of Cell used to display data in the column Matrices of 
NXBrowser. Many of NXBrowserCell’s methods are designed to interact with 
NXBrowser and NXBrowser’s delegate. The delegate implements methods for loading 
the Cells in NXBrowser by setting their values and status. If you need access to a 
specific NXBrowserCell, you can use the NXBrowser method 
getLoadedCellAtRowiinColumn:. 

You may find it useful to subclass NXBrowserCell to alter its behavior and to enable it 
to work with and display the type of data you wish to represent. Use NXBrowser’s 
setCellClass: or setCellPrototype: methods to use your subclass. 

See also: NXBrowser 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Cell 

char 

*contents; 


id 

support; 


struct _cFlagsl 

cFlagsl; 


struct _cFlags2 

cFlags2; 


METHOD TYPES 

Creating an NXBrowserCell - init 

- initTextCell: 

Determining icons + branchlcon 

+ branchlconH 

Determining component sizes - calcCellSize:inRect: 

Displaying - drawInsiderinView: 

- drawSelfrinView: 

Highlighting behavior - highlight:inView:lit: 
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Placing in browser hierarchy 

- isLeaf 

- setLeaf: 

Determining loaded status 

- isLoaded 

- setLoaded: 

Determining reset status 

- reset 

Modifying graphic attributes 

- isOpaque 


CLASS METHODS 

branchlcon 
+ branchlcon 

Returns the id of the NXImage object “NXMenuArrow.” This is the icon displayed to 
indicate a branch node in an NXBrowserCell. Override this method if you want to 
display a different branch icon. 

See also: - isBranch, - setBranch 

branchlconH 
+ branchlconH 

Returns the id of the NXImage object “NXMenuArrowH.” This is the highlighted icon 
displayed to indicate a branch node in an NXBrowserCell. Override this method if you 
want to display a different branch icon. 

See also: - isBranch, - setBranch 


INSTANCE METHODS 

calcCellSize:inRect: 

- calcCellSize:(NXSize *)theSize inRect: (const NXRect *)aRect 

Calculates the minimum width and height required for displaying the NXBrowserCell 
in a given rectangle. Makes sure theSize remains large enough to accommodate the 
branch arrow icon. If it isn’t possible for the NXBrowserCell to fit in aRect , the width 
and/or height returned in theSize could be bigger than those of the rectangle. The 
computation is done by trying to size the NXBrowserCell so that it fits in the rectangle 
argument (by wrapping the text, for instance). If a choice must be made between 
extending the width or height of aRect to fit the text, the height will be extended. 
Returns self and, by reference, the minimum size for the NXBrowserCell. 
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drawInside:inView: 

- drawlnside: (const NXRect *)cellFrame in View: controlView 

Draws the inside of the NXBrowserCell (that is, it’s the same as drawSe!f:inView: 
except that it doesn’t draw the bezel or border if there is one). Returns self. 

drawSelfiinView: 

- drawSelf: (const NXRect *)cellFrame inView '.controlView 

Draws the NXBrowserCell, including the bezel or border. Returns self. 

See also: - drawInside:inView: 

highlight:inView:lit: 

- highlight: (const NXRect *)cellFrame inView: '.controlView lit:(BOOL)lit 
Sets the highlighted state to lit and redraws the NXBrowserCell. Returns self. 

See also: - reset 


init 


- init 


Initializes and returns the receiver, a new NXBrowserCell instance, by invoking the 
initTextCell: method. Sets the NXBrowserCell’s string value to “Browserltem” and 
returns self. 


initTextCell: 

- initTextCell: (const char *)aString 


Initializes the receiver, a new NXBrowserCell instance, by sending the message 
[super initTextCelhaSfrmg]. Sets the NXBrowserCell so it doesn’t wrap text. 
Returns self. This method is the designated initializer for the NXBrowserCell class. 
Override this method if you create a subclass of NXBrowserCell that performs its own 
initialization. 


isLeaf 

- (BOOL)isLeaf 

Determines whether the entry in the receiver represents a leaf node (such as a file) or 
branch node (such as a directory). This method is invoked by NXBrowser to check 
whether to display the branch icon in the Cell and, when an NXBrowserCell is selected, 
whether to load a column to the right of the column containing the receiving Cell. 
Returns YES if the cell represents a leaf, NO if the cell represents a branch. 

See also: - setLeaf: 
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isLoaded 


- (BOOL)isLoaded 

Returns YES if the NXBrowserCell is loaded, NO if it isn’t. Used by NXBrowser to 
determine if a particular Cell is loaded in a column. When an NXBrowserCell is 
created, this value is YES. NXBrowser and its delegate change the value returned by 
this method using the setLoaded: method to reflect the current status of the cell. 

See also: - setLoaded: 

isOpaque 

- (BOOL)isOpaque 

Returns YES if the NXBrowserCell is opaque (that is, it touches every pixel in its 
bounds). 


reset 

- reset 

Sets the NXBrowserCell’s state to 0, sets the highlighted flag to NO, and returns self. 
See also: - highlight:inView:lit 

setLeaf: 

- setLeaf : (BOOlflflag 

Invoked by NXBrowser’s delegate when it loads an NXBrowserCell. When flag is 
YES, the NXBrowserCell represents a leaf node; it will display without the branch 
icon. When flag is NO, the NXBrowserCell represents a branch node; it will display 
with the branch icon. 

See also: - branchlcon, - branchlconH, - isLeaf 
setLoaded: 

- setLoaded :(BOOL)/?ag 

Sets the loaded status of the NXBrowser cell to flag. This method is invoked by 
NXBrowser or its delegate to set the status of the NXBrowserCell. The delegate should 
send the setLoaded: message with YES as the argument when it loads the cell. 

See also: - isLoaded, “METHODS IMPLEMENTED BY THE DELEGATE” 
(NXBrowser) 
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NXCachedlmageRep 


INHERITS FROM NXImageRep : Object 

DECLARED IN appkit/NXCachedlmageRep.h 

CLASS DESCRIPTION 

An NXCachedlmageRep is a rendered image in a window, typically a window that 
stays off-screen. The only data that’s available for reproducing the image is the image 
itself. Thus an NXCachedlmageRep differs from the other kinds of NXImageReps 
defined in the Application Kit, all of which can reproduce an image from the 
information originally used to draw it. 

Instances of this class are generally used indirectly, through an NXImage object. An 
NXCachedlmageRep must be able to provide the NXImage with some information 
about the image—so that the NXImage can match it to a display device, for example, 
or know whether to scale it. Therefore, it’s a good idea to use these inherited methods 
to inform the NXCachedlmageRep object about the image in the cache: 

setNumColors: 

setAlpha: 

setPixelsHigh: 

setPixelsWide: 

setBitsPerSample: 

These methods are all defined in the NXImageRep class. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from NXImageRep 

NXSize 

size; 

Declared in NXCachedlmageRep 

(none) 
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METHOD TYPES 


Initializing a new NXCachedlmageRep 

- initFromWindow:rect: 

Freeing an NXCachedlmageRep - free 

Getting the representation - getWindow:andRect: 

Drawing the image - draw 

Archiving - read: 

- write: 


INSTANCE METHODS 

draw 

- (BOOL)draw 

Reads image data from the cache and reproduces the image from that data. The 
reproduction is rendered in the current window at location (0.0,0.0) in the current 
coordinate system. 

It’s much more efficient to reproduce an image by compositing it, which can be done 
through the NXImage class. An NXBitmapImageRep can also be used to reproduce an 
existing image. 

This method returns YES if successful in reproducing the image, and NO if not. 

See also: - drawln: (NXImageRep), - drawAt: (NXImageRep), 

- initDatarfromRect: (NXBitmapImageRep) 

free 

- free 

Deallocates the NXCachedlmageRep. 

getWindow:andRect: 

- get Window: (Window **)theWindow andRect:(NXRect *)theRect 

Copies the id of the Window object where the image is located into the variable referred 
to by theWindow, and copies the rectangle that bounds the image into the structure 
referred to by theRect. If theRect is NULL, only the Window id is provided. Returns 
self. 
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init 


Generates an error message. This method cannot be used to initialize an 
NXCachedlmageRep. Use the initFromWindowrrect: method instead. 

See also: - initFromWindow:rect: 
initFromWindow:rect: 

- initFromWindow: (Window *)aWindow rect: (const NXRect *)aRect 

Initializes the receiver, a new NXCachedlmageRep instance, for an image that will be 
rendered within the aRect rectangle in aWindow, and returns the initialized object. The 
rectangle is specified in aWindow’s base coordinate system. The size of the image is 
set from the size of the rectangle. 

You must draw the image in the rectangle yourself; there are no NXCachedlmageRep 
methods for this purpose. 

read: 

- read:(NXTypedStream *)stream 

Reads the NXCachedlmageRep from the typed stream stream. 


write: 

- write :(NXTypedStream *)stream 

Writes the NXCachedlmageRep to the typed stream stream. 
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NXColorPanel 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN appkit/NXColorPanel.h 

CLASS DESCRIPTION 

NXColorPanel provides a standard user interface for selecting color in an application. 
It provides seven color selection modes, including four that correspond to 
industry-standard color models. It allows the user to set swatches containing frequently 
used colors. Once set, these swatches are displayed by NXColorPanel in any 
application where it is used, giving the user color consistency between applications. 
The NXColorPanel also enables the user to capture a color anywhere on the screen for 
use in the active application, and to drag colors between views in an application. 

The color mask determines which of the color modes are enabled for NXColorPanel. 
This mask is set by using color mask constants when you initialize a new instance of 
NXColorPanel. When an instance of NXColorPanel is masked for more than one color 
mode, your program can set its mode by invoking the setMode: method with a color 
mode constant as its argument; the user can set the mode by clicking buttons on the 
panel. Here are the color modes with corresponding mask and mode constants: 


Mode 

Grayscale-Alpha 

Color Mask/Color Mode Constants 

NX_GRAYMODEMASK 

NX_GRAYMODE 

Red-Green-Blue 

NX_RGBMODEMASK 

NX_RGBMODE 

Cyan-Yellow-Magenta-Black 

NX_CMYKMODEMASK 

NX_CMYKMODE 

Hue-Saturation-Brightness 

NX_HSBMODEMASK 

NX.HSBMODE 

TIFF image 

NX_CU STOMPALETTEMODEMASK 
NX_CU STOMPALETTEMODE 

Custom color lists 

NX_CUSTOMCOLORMODEMASK 
NX_CU STOMCOLORMODE 

Color wheel 

nx_beginmodemask 

NX.BEGINMODE 

All of the above 

NX_ALLMODESMASK 

none 
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NX_ALLMODESMASK represents the logical OR of the other color mask constants. 
When NXColorPanel is initialized using NX_ALLMODESMASK, it can be set to any 
of the modes. When initializing a new instance of NXColorPanel, you can logically 
OR any combination of color mask constants to restrict the available color modes. 

In grayscale-alpha, red-green-blue, cyan-magenta-yellow-black, and 
hue-saturation-brightness modes, the user adjusts colors by manipulating sliders. In the 
custom palette mode, the user can load a TIFF file into the NXColorPanel, then select 
colors from the TIFF image. In custom color list mode, the user can create and load 
lists of named colors. The two custom modes provide PopUpLists for loading and 
saving files. Finally, color wheel mode provides a simplified control for selecting 
colors; by default, it’s the initial mode when the NX_ALLMODESMASK constant is 
used to initialize the NXColorPanel. 

NXColorPanel’s action message is sent to the target object when the user changes the 
current color. 

An application has only one instance of NXColorPanel, the shared instance. Once the 
shared instance has been created, invoking any of the new methods returns the shared 
instance rather than a new NXColorPanel. 

One of NXColorPanel’s methods, dragColor:withEvent:fromView:, allows colors to 
be moved between Views in an application. For example, NXColorWell invokes this 
method from its mouseDown: method to allow you to move colors from a well to other 
views. Any View can implement the acceptColoriatPoint: method to accept a color 
dragged from an NXColorWell or NXColorPanel. 

You can put NXColorPanel in any application created with Interface Builder by adding 
the “Colors...” item from the Menu palette to the application’s menu. 

See also: NXColorWell 


INSTANCE VARIABLES 



Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 
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Inherited from Window 

NXRect 

id 

id 

id 

id 

id 

id 

id 

int 

int 

float 

struct _wFlags 
struct _wFlags2 

frame; 

contentView; 

delegate; 

firstResponder; 

lastLeftHit; 

lastRightHit; 

counterpart; 

fieldEditor; 

winEventMask; 

windowNum; 

backgroundGray; 

wFlags; 

wFlags2; 

Inherited from Panel 

(none) 


Declared in NXColorPanel 

(none) 


METHOD TYPES 



Creating a New NXColorPanel 

+ newContent:style:backing:buttonMask:defer: 

+ newContent: sty le :backing :buttonMask: defer: 

colorMask: 

+ newMask: 

+ sharedlnstance: 

Setting NXColorPanel Behavior 

- colorMask 

- setColorMask: 

- setContinuous: 

- setMode: 

- set Accessory View: 

- setShow Alpha: 


Setting Color 

+ dragColor:withEvent:fromView: 

- color 

- setColor: 

- updateCustomColorList 

Target and Action 

- setAction: 

- setTarget: 
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CLASS METHODS 


dragCoIor:withEvent:fromView: 

+ (BOOL)dragCoIor : (NXColor)co/or 
withEvent:(NXEvent*)?/ze£ve«r 
fromView icontrolView 

Allows colors to be dragged between views in an application. This method is usually 
invoked by the mouseDown: method of controlView; the mouseDown: method sets up 
a modal loop until the subsequent NXJMOUSEUP event occurs, then sends this 
message to the NXColorPanel class object. theEvent is always the NX_MOUSEUP 
event; this method uses the cursor coordinates from theEvent to determine the receiving 
View. 

To accept the dragged color, the receiving view must implement the method 
acceptColor:(NXColor)co/or atPoint:(NXPoint)ra<mseU/?/ > c>/«r. The only View 
subclass in the application kit that implements this method is NXColorWell. 
Implementing acceptColoriatPoint: in a View subclass is described in “METHODS 
IMPLEMENTED BY A VIEW SUBCLASS” at the end of this section. 

Because it is a class method, dragColor:withEvent:fromView: can be used whether 
or not an instance of NXColorPanel exists. Returns YES. 

See also: - mouseDown: (NXColorWell), - acceptColoriatPoint: in “METHODS 
IMPLEMENTED BY A VIEW SUBCLASS” below and in NXColorWell 

newContent:style:backing:buttonMask:defer: 

+ newContent: (const NXRect *)contentRect 
style: (in t)aStyle 
backing:(int)bufferingType 
buttonMask: (int)mask 
defer:(BOOL)/?ag 

Invokes the newContent:style:backing:buttonMask:defer:colorM[ask: method with 
NX_ALLMODESMASK as the argument. This method is implemented to override the 
method inherited from the Panel class. 

See also: + newContent:style:backing:buttonMask:defer:colorMask: 
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newContent:style:backing:buttonMask:defer:colorMask: 

+ newContent:(const NXRect *)contentRect 
style:(int )aStyle 
backing: (int )bufferingType 
buttonMask: (int) mask 
defer:(BOOL )flag 
colorMask: (int )colormask 

Creates, if necessary, and returns the shared instance of NXColorPanel. Only one 
instance of NXColorPanel can be created in an application. This method allocates a 
new instance of NXColorPanel from its own zone, then initializes it by invoking the 
initContent:style:backing:buttonMask:defer:colorMask: method. The 
newColorMask: method below lists the constants to use for colormask. 

See also: + newColorMask: 

newColorMask: 

+ newMask:(int )colormask 

Creates, if necessary, and returns the shared instance of the NXColorPanel. Only one 
instance of NXColorPanel can be created in an application. This method allocates a 
new instance of NXColorPanel from its own zone, then initializes it by invoking the 
initColorMask: method. 

To set the color selection modes available in a new instance of NXColorPanel, use one 
of the following constants for colormask : 

NX_GRAYMODEMASK 

NX_RGBMODEMASK 

NX_CMYKMODEMASK 

NX.HSBMODEMASK 

NX_CU STOMPALETTEMODEM ASK 

NX_CUSTOMCOLORMODEMASK 

NX_BEGINMODEMASK 

NX_ALLMODESMASK 

To enable multiple selection modes for the new NXColorPanel, use a colormask 
expression containing the logical OR of two or more color mask constants. 
NX_ALLMODESMASK represents the logical OR of all the other masks. 

To change the color selection modes available in an existing instance of 
NXColorPanel, use the setColorMask method. 

See also: - color Mask, - setColorMask, - setMode 
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sharedlnstance 


+ sharedInstance:(BOOL)cre< 2 te 

Tests for the shared instance of NXColorPanel. If create is NO and the shared instance 
exists, this method returns its id; if no instance of NXColorPanel exists, returns nil. If 
create is YES, this method creates, if necessary, and returns the id of the shared 
NXColorPanel. 


INSTANCE METHODS 

alloc 

Generates an error message. This method cannot be used to create NXColorPanel 
instances. Use the newFrame: method instead. 

See also: + newFrame: 

allocFromZone 

Generates an error message. This method cannot be used to create NXColorPanel 
instances. Use the newFrame: method instead. 

See also: + newFrame: 

color 

- (NXColor)color 

Returns the current color selection of the NXColorPanel. 

See also: - setColor 

colorMask 

- (int)colorMask 

Returns the color mask. The return value will be one of the color mask constants 
described in the newMask: method or a logical OR of two or more of the constants. 

See also: + newMask: 
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setAccessoryView: 

- setAccessoryView:<3V7m’ 

Sets the accessory view displayed in the NXColorPanel to aView. The accessory View 
can be any custom View that you want to display with NXColorPanel, for example, a 
View offering patterns or brush shapes in a drawing program. The accessory View is 
displayed below the regular controls in the NXColorPanel. The NXColorPanel 
automatically resizes to accommodate the accessory View. Returns self. 

set Action: 

- setAction:(SEL)aSe/ecror 

Sets the action of the NXColorPanel to aSelector. Returns self. 
setColor: 

- setColor:(NXColor )color 

Sets the color setting of the NXColorPanel to color and redraws the panel. Returns self. 

setColor Mask: 

- setColorMask:(int )colormask 

Sets the color mode mask of the NXColorPanel. Returns self. 


set Continuous: 

- setContinuous:(BOOL)//ag 

Sets the NXColorPanel to send the action message to its target continuously as the color 
of the NXColorPanel is set by the user. Send this message with flag YES if, for 
example, you want tot continuously update the color of the target. Returns self. 
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setMode: 


- setMode: (int )mode 

Sets the mode of the NXColorPanel if mode is one of the modes allowed by the color 
mask. The color mask is set when you first create the shared instance of NXColorPanel 
for an application, mode can be one of seven constants: 

NX_GRAYMODE 

NX_RGBMODE 

NX_CMYKMODE 

NX_HSBMODE 

NX_CUSTOMPALETTEMODE 

NX_CUSTOMCOLORMODE 

nx_beginmode 

Color modes and masks are described in more detail in “CLASS DESCRIPTION” at 
the beginning of this discussion. 

Returns self. 

See also: “CLASS DESCRIPTION” 

setShowAIpha: 

- setShowAlpha:(BOOL)//< 2 £ 

If flag is YES, sets the NXColorPanel to show alpha. Returns self. 

setTarget: 

- setTarget:anObject 

Sets the target of the NXColorPanel. The NXColorPanel’s target is the object to which 
the action message is sent when the user selects a color. Returns self. 

See also: - setAction, - setContinuous 

updateCustomColorList 

- updateCustomColorList 

Updates the custom color list to reflect the current entries. This method is invoked by 
Controls on the NXColorPanel in NX_CUSTOMCOLORMODE. 
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METHODS IMPLEMENTED BY A VIEW SUBCLASS 


acceptColorratPoint: 

- acceptColor:(NXColor)c<9/<9r atPoint:(NXPoint *)aPoint 

Allows the View to accept color when aPoint is a point within its bounds. Implement 
this method if you want to be able to drag a color from an NXColorPanel or 
NXColorWell into your subclass of View. This method is invoked by NXColorPanel’s 
class method dragColor:withEvent:fromView:. Returns self. 

See also: - acceptColor:atPoint: in NXColorWell, 

+ dragColor:withEvent:fromView: 


CONSTANTS 


tdefine NX_GRAYMODE 0 
#define NX_RGBMODE 1 
#define NX_CMYKMODE 2 
#define NX_HSBMODE 3 
#define NX_CUSTOMPALETTEMODE 4 
#define NX_CUSTOMCOLORMODE 5 
#define NX_BEGINMODE 6 

#define NX_GRAYMODEMASK 1 
#define NX_RGBMODEMASK 2 
#define NX_CMYKMODEMASK 4 
#define NX_HSBMODEMASK 8 
#define NX_CUSTOMPALETTEMODEMASK 16 
#define NX_CUSTOMCOLORMODEMASK 32 
#define NX BEGINMODEMASK 64 


#define NX_ALLMODESMASK \ 
(NX_GRAYMODEMASK| \ 

NX_RGBMODEMASK| \ 
NX_CMYKMODEMASK| \ 
NX_HSBMODEMASK| \ 
NX_CUSTOMPALETTEMODEMASK| \ 
NX_CUSTOMCOLORMODEMASK! \ 
NX_BEGINMODEMASK) 
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NXColorWell 


INHERITS FROM Control: View: Responder: Object 

DECLARED IN appkit/NXColorWell.h 

CLASS DESCRIPTION 

NXColorWell is a Control for selecting and displaying a single color value. An 
example of NXColorWell is found in NXColorPanel, which uses a well to display the 
current color selection. NXColorWell is available from the Palettes panel of Interface 
Builder. 

An application can have one or more active NXColorWells. You can activate multiple 
NXColorWells by invoking the activate: method with NO as its argument. You can set 
the same color for all active color wells by invoking the class method 
activeWellsTakeColorFrom:. You can deactivate multiple wells using the class 
method deactivate All Wells. When a mouse-down event occurs in an NXColorWell, it 
becomes the only active well. 

The mouseDown: method enables an instance of NXColorWell to send its color to 
another NXColorWell or any other subclass of View that implements the 
acceptColor:atPoint: method. NXColorWell’s mouseDown: method invokes 
NXColorPanel’s dragColor:withEvent:fromView: class method, which sends an 
acceptColor:atPoint: message to the receiving View. 

See also: NXColorPanel 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

NXRect 

id 

id 

id 

struct_vFlags 

frame; 

bounds; 

superview; 

subviews; 

window; 

vFlags; 

Inherited from Control 

int 

id 

struct _conFlags 

tag; 

cell; 

conFlags; 

Defined in NXColorWell 

NXColor 

color; 


color The current color value of the NXColorWell 
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METHOD TYPES 


Initializing an NXColorWell 
Multiple NXColorWells 


Drawing 


Handling events 


Activating and enabling 


Setting color 


Target and action 


- initFrame: 

+ active WellsTakeColorFrom: 

+ active WellsTakeColorFromrcontinuous: 
+ deactivateAllWells 

-drawSelf:: 

- drawWelllnside: 

- acceptsFirstMouse 

- mouseDown: 

- isContinuous 

- setContinuous: 

- activate: 

- deactivate 

- isActive 

- setEnabled: 

- acceptColoriatPoint: 

- setColor: 

- color 

- takeColorFrom: 

- target 

- action 

- setTarget: 

- setAction: 


CLASS METHODS 


activeWellsTakeColorFrom: 

+ active WellsTakeColorFrom:seflder 

This method changes the color of all active NXColorWells by invoking their 
takeColorFrom: method with sender as the argument. Returns the NXColorWell class 
object. 

See also: - activate:, + activeWelIsTakeColorFrom:continuous:, - deactivate, 

+ deactivateAllWells, - takeColorFrom: 
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activeWellsTakeColorFrom:continuous 

+ activeWellsTakeColorFrom '.sender continuous:(BOOL )flag 

If flag is YES, this method continuously changes the color of all active NXColor Wells 
that are continuous; If NO, all active NXColorWells, continuous or not, change their 
color just once. NXColorWells are updated by invoking their takeColorFrom: method 
with sender as the argument. Use this method with YES as the flag in a modal event 
loop if you want active NXColorWells to continuously update to reflect the current 
color of sender. Returns the NXColorWell class object. 

See also: - activate:, - deactivate, + deactivateAllWells, - isContinuous, 

- setContinuous:, - takeColorFrom: 

deactivateAllWells 
+ deactivateAllWells 

Deactivates all currently active NXColorWells. Returns the NXColorWell class object. 
See also: - activate:, - deactivate 


INSTANCE METHODS 


acceptColor:atPoint: 

- acceptColor:(NXColor)co/or atPoint:(NXPoint *)aPoint 

Changes the color value of the NXColorWell to color when aPoint is a point within the 
bounds of the NXColorWell. This method is invoked by the NXColorPanel method 
dragColor:withEvent:fromView: to move color into an NXColorWell. Returns self. 

Note that any subclass of View can accept colors from an NXColorWell by 
implementing a version of this method. 

See also: - dragColor:withEvent:fromView: (NXColorPanel) 

acceptsFirstMouse 

- acceptFirstMouse 

Returns YES. 

action 

- action 

Returns the action sent by the NXColorWell to the target. 
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activate: 


- (mt)activate:(int)e*c/«.S7ve 

If exclusive is YES, this method activates the receiving NXColorWell and deactivates 
any other active NXColorWells. If NO, this method activates the receiving 
NXColorWell and keeps previously active NXColorWells active. Redraws the receiver. 
An active NXColorWell will have its color updated as the NXColorPanel’s current 
color changes. 

This method returns the number of active NXColorWells. 

See also: + activeWellsTakeColorFrom:, - deactivate 

color 

- (NXColor)color 

Returns the color of the NXColorWell. 

See also: - acceptColonatPoint, - setColor:, - takeColorFrom: 

deactivate 

- deactivate 

Sets the NXColorWell to inactive and redraws it. Returns self. 
drawSelf:: 

- drawSelf: (const NXRect *)rects:(int)rectCount 

Draws the entire NXColorWell, including its border. Returns self. 

drawWelllnside: 

- drawWelllnside: (const NXRect *)insideRect 

Draws the inside of the NXColorWell only, the area where the color is displayed. 
Returns self. 


initFrame: 

- initFrame: (NXRect const *)theFrame 

’ Initializes and returns the receiver, a new instance of NXColorPanel within theFrame. 
By default, the color is NX_COLORWHITE and the NXColorWell is bordered and 
inactive. Returns self. 
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isActive 

- (BOOL)isActive 

Returns YES if the receiving NXColorWell is active, NO if not active. 

mouseDown: 

- mouseDown: (NXEvent *)theEvent 

Makes the receiver the only active NXColorWell. If theEvent occurs within the colored 
area of the NXColorWell (not on its border), then this method invokes NXColorPanel’s 
dragColor:withEvent:fromView: method. The user can then drag the color from the 
NXColorWell to another View that has an acceptColor: atPoint : method, such as 
another NXColorWell. Returns self. 

You never invoke this method. It’s sent when an NX_MOUSEDOWN event occurs 
within the bounds of the NXColorWell. 

See also: - acceptColoriatPoint:, - activate, - deactivate, 

+ dragColor:withEvent:fromView: (NXColorPanel), - isActive 

set Action: 

- setAction:(SEL) aSelector 

Sets the default action method of the NXColorWell. The action message is sent to the 
target by NXColorWell’s acceptColorratPoint: and takeCoIorFrom: methods. 
Returns self. 


setColor: 

- setColor:(NXColor )color 

Sets the color of the NXColorWell to color and redraws it. Returns self. 


setContinuous: 

- setContinuous: (BOOL)/?<2g 

li flag is YES, the NXColorWell continuously updates its color and sends its action 
message to its target in response to an activeWellsTakeColorFrom:continuous:. If 
NO, the NXColorWell doesn’t respond to this message. Returns self. 
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setEnabled: 

- setEnabled: (BOOL)/?^ 

If flag is YES, the receiving NXColorWell is enabled. If NO, the receiver is disabled. 
An NXColorWell cannot be both disabled and active; enabling an NXColorWell 
doesn’t activate. Returns self. 

See also: - activate, - deactivate, - isActive 

setTarget: 

- setTarg etianObject 

Sets the target of the NXColorWell. The action message is sent to the target by 
NXColorWell’s acceptColoriatPoint: and takeCoIorFrom: methods. Returns self. 

takeColorFrom 

- takeColorFrom: sender 

Causes the receiving NXColorWell to set its color by sending a color message to 
sender. Sends the NXColorWell’s action message to its target and returns self. 

See also: -color 

target 

- target 

Returns the target of the NXColorWell. The action message is sent to the target by 
NXColorWell’s acceptColor:atPoint: and takeColorFrom: methods. Returns self. 

See also: - setTarget: 
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NXCursor 


INHERITS FROM Object 

DECLARED IN appkit/NXCursor 

CLASS DESCRIPTION 

An NXCursor object holds an image that can become the image the Window Server 
displays for the cursor. A set message makes the receiver the current cursor: 

[myNXCursor set]; 


For automatic cursor management, an NXCursor can be assigned to a cursor rectangle 
within a window. When the window is the key window and the user moves the cursor 
into the rectangle, the NXCursor is set to be the current cursor. It ceases to be the 
current cursor when the cursor leaves the rectangle. The assignment is made using 
View’s addCursorRect:cursor: method, usually inside a resetCursorRects method: 

- resetCursorRects 
{ 

[self addCursorRect:SsomeRect cursor:theNXImageObject]; 
return self; 

} 

This is the recommended way of associating a cursor with a particular region inside a 
window. However, the NXCursor class provides two other ways of setting the cursor: 

• The class maintains its own stack of cursors. Pushing an NXCursor instance on the 
stack sets it to be the current cursor. Popping an NXCursor from the stack sets the 
next NXCursor in line, the one that’s then at the top of the stack, to be the current 
cursor. 

• An NXCursor can be made the owner of a tracking rectangle and told to set itself 
when it receives a mouse-entered or mouse-exited event. 

The Application Kit provides two ready-made NXCursor instances and assigns them to 
global variables: 

NXArrow The standard arrow cursor 

NXIBeam The cursor that’s displayed over editable or selectable text 

There’s no NXCursor instance for the wait cursor. The wait cursor is displayed 
automatically by the system, without any required program intervention. 
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INSTANCE VARIABLES 


Inherited from Object 
Declared in NXCursor 


hotSpot 


Class 


isa; 


NXPoint 
struct _csrFlags { 
unsigned int 
unsigned int 

} 

id 


hotSpot; 


onMouseExited: 1; 
onMouseEntered: 1; 
cFlags; 
image; 


The point in the cursor image whose location on 
the screen is reported as the cursor’s location. 


cFlags.onMouseExited A flag indicating whether to set the cursor when 

the Cursor object receives a mouse-exited event. 

cFlags.onMouseEntered A flag indicating whether to set the cursor when 

the Cursor object receives a mouse-entered event. 


image 


The cursor image, an NXImage object. 


METHOD TYPES 

Initializing a new NXCursor object - init 

- initFromlmage: 

Defining the cursor - setlmage: 

- image 

- setHotSpot: 

Setting the cursor - push 

-pop 
+ pop 

- set 

- setOnMouseEntered: 

- setOnMouseExited: 

- mouseEntered: 

- mouseExited: 

+ currentCursor 

Archiving - read: 

- write: 
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CLASS METHODS 


currentCursor 
+ currentCursor 

Returns the last NXCursor to have been set. 

See also: - set, - push, + pop, - mouseEntered:, - mouseExited:, 


pop 
+ pop 

Removes the NXCursor currently at the top of the cursor stack, and sets the NXCursor 
that was beneath it (but is now at the top of the stack) to be the current cursor. Returns 
self (the class object). 

This method can be used in conjunction with the push method to manage a group of 
cursors within a local context. Every push should be balanced by a subsequent pop. 
When the last remaining cursor is popped from the stack, the Application Kit restores 
a cursor appropriate for the larger context. 

The pop instance method provides the same functionality as this class method. 

See also: - push 


INSTANCE METHODS 


image 
- image 

Returns the NXImage object that supplies the cursor image for the receiving NXCursor. 
See also: - initFromlmage:, - setlmage: 


init 


- init 


Initializes the receiver, a newly allocated NXCursor instance, by sending it an 
initFromlmage: message with nil as the argument. This doesn’t assign an image to 
the object. An image must then be set (with the setlmage: method) before the cursor 
can be used. Returns self. 

See also: - setlmage:, - initFromlmage: 
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initFromlmage: 

- initF romlmage : image 

Initializes the receiver, a newly allocated NXCursor instance, by setting the image it 
will use to image, an NXImage object. For a standard cursor, the image should be 16 
pixels wide by 16 pixels high. The default hot spot is at the upper left comer of the 
image. 

This method is the designated initializer for the class. Returns self. 

See also: -setHotSpot: 

mouseEntered: 

- mouseEntered: (NXEvent *)theEvent 

Responds to a mouse-entered event by setting the NXCursor to be the current cursor, 
but only if enabled to do so by a previous setOnMouseEntered: message. This 
method does not push the receiver on the cursor stack. Returns self. 

See also: - setOnMouseEntered: 

mouseExited: 

- mouseExited: (NXEvent *)theEvent 

Responds to a mouse-exited event by setting the NXCursor to be the current cursor, but 
only if enabled to do so by a previous setOnMouseExited: message. This method does 
not push the receiver on the cursor stack. Returns self. 

See also: - setOnMouseExited: 


pop 

-pop 

Removes the topmost NXCursor object, not necessarily the receiver, from the cursor 
stack, and makes the next NXCursor down the current cursor. Returns self. 

This method is an interface to the class method with the same name. 

See also: + pop, - push 
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push 

- push 

Puts the receiving NXCursor on the cursor stack and sets it to be the Window Server’s 
current cursor. Returns self. 

This method can be used in conjunction with the pop method to manage a group of 
cursors within a local context. Every push should be matched by a subsequent pop. 

See also: + pop 

read: 

- read:(NXTypedStream *)stream 

Writes the NXCursor, including the image, to stream. 

See also: - write: 


set 

- set 

Makes the NXCursor the current cursor displayed by the Window Server, and returns 
self. This method doesn’t push the receiver on the cursor stack. 

setHotSpot: 

- setHotSpot: (const NXPoint *)aPoint 

Sets the point on the cursor that will be used to report its location. The point is specified 
relative to a flipped coordinate system with an origin at the upper left comer of the 
cursor image and coordinate units equal to those of the base coordinate system. The 
point should not have any fractional coordinates, meaning that it should lie at the comer 
of four pixels. The point selects the pixel below it and to its right. This pixel is the one 
part of the cursor image that’s guaranteed never to be off-screen. 

When the pixel selected by the hot spot lies inside a rectangle (say a button), the cursor 
is said to be over the rectangle. When the pixel is outside the rectangle, the cursor is 
taken to be outside the rectangle, even if other parts of the image are inside. 

The default hot spot is at the upper left comer of the image. Returns self. 
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setlmage: 

- setlmage '.image 

Sets a new image for the NXCursor, and returns the old image. The new image should 
be an NXImage object. If the old image is of no further use, it should be freed. 
Resetting the image while the cursor is displayed may have unpredictable results. 

See also: - image, - initFromlmage: 

setOnMouseEntered: 

- setOnMouseEntered:(BOOL)/7(2g 

Determines whether the NXCursor should set itself to be the current cursor when it 
receives a mouseEntered: event message. To be able to receive the event message, an 
NXCursor must first be made the owner of a tracking rectangle by Window’s 
setTrackingRect:inside:owner:tag:Ieft:right: method. 

Cursor rectangles are a more convenient way of associating cursors with particular 
areas within a window. 

Returns self. 

See also: - mouseEntered:, - setTrackingRect:inside:owner:tag:Ieft:right: 
(Window) 

setOnMouseExited: 

- setOnMouseExited :(BOOL)flag 

Determines whether the NXCursor should set itself to be the current cursor when it 
receives a mouseExited: event message. To be able to receive the event message, an 
NXCursor must first be made the owner of a tracking rectangle by Window’s 
setTrackingRect:inside:owner:tag:left:right: method. 

Cursor rectangles are a more convenient way of associating cursors with particular 
areas within windows. 

Returns self. 

See also: - mouseExited:, - setTrackingRect:inside:owner:tag:left:right: 
(Window) 


write: 

- write :(NXTypedStream *)stream 
Writes the NXCursor and its image to stream. 
See also: - read: 
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NXCustomlmageRep 


INHERITS FROM NXImageRep : Object 

DECLARED IN appkit/NXCustomlmageRep.h 


CLASS DESCRIPTION 

An NXCustomlmageRep is an object that uses a delegated method to render an image. 
When called upon to produce the image, it sends a message to have the method 
performed. 

Like most other kinds of NXImageReps, an NXCustomlmageRep is generally used 
indirectly, through an NXImage object. To be useful to the NXImage, it must be able 
to provide some information about the image. The following methods, inherited from 
the NXImageRep class, inform the NXCustomlmageRep about the size of the image, 
whether it can be drawn in color, and so on. Use them to complete the initialization of 
the object. 

setSize: 

setNumColors: 

setAlpha: 

setPixelsHigh 

setPixelsWide 

setBitsPerSample: 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from NXImageRep 

NXSize 

size; 

Declared in NXCustomlmageRep 

SEL 

drawMethod; 


id drawObject; 

The method that draws the image. 

The object that receives messages to perform the 

drawMethod. 


drawMethod 

drawObject 
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METHOD TYPES 


Initializing a new NXCustomlmageRep 

- initDrawMethodiinObject: 

Drawing the image - draw 

Archiving - read: 

- write: 

INSTANCE METHODS 

draw 

- (BOOL)draw 

Sends a message to have the image drawn. Returns YES if the message is successfully 
sent, and NO if not. The message will not be sent if the intended receiver is nil or it 
can’t respond to the message. 

See also: - drawAt: (NXImageRep), - drawln: (NXImageRep) 

init 

Generates an error message. This method cannot be used to initialize an 
NXCustomlmageRep. Use initDrawMethod:inObject: instead. 

See also: - initDrawMethod:inObject: 

initDrawMethod:inObject: 

- initDrawMethod :($>EL)aSelector inObject: anObject 

Initializes the receiver, a newly allocated NXCustomlmageRep instance, so that it 
delegates responsibility for rendering the image to anObject. When the 
NXCustomlmageRep receives a draw message, it will in turn send a message to 
anObject to perform the aSelector method. The aSelector method should take only one 
argument, the id of the NXCustomlmageRep. It should draw the image at location 
(0.0,0.0) in the current coordinate system. 

Returns self. 

read: 

- read:(NXTypedStream *)stream 

Reads the NXCustomlmageRep from the typed stream stream. 

See also: - write: 
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write: 

- write :(NXTypedStream *)stream 

Writes the NXCustomlmageRep to the typed stream stream. The object that’s 
delegated to draw the image is not explicitly written. 

See also: - read: 
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NXEPSImageRep 


INHERITS FROM NXImageRep : Object 

DECLARED IN appkit/NXEPSImageRep 


CLASS DESCRIPTION 

An NXEPSImageRep is an object that can render an image from encapsulated 
PostScript code (EPS). The size of the object is set from the bounding box specified in 
the EPS header comments. Other information about the image should be supplied 
using inherited NXImageRep methods. 

Like most other kinds of NXImageReps, an NXEPSImageRep is generally used 
indirectly, through an NXImage object. 


INSTANCE VARIABLES 


Inherited from Object 
Inherited from NXImageRep 
Declared in NXEPSImageRep 


Class 

isa; 

NXSize 

size; 

(none) 



METHOD TYPES 

Initializing a new NXEPSImageRep instance 

- initFromSection: 

- initFromFile: 

- initFromStream: 

Creating a List of NXEPSImageReps 

+ newListFromSection: 

+ newListFromSection: zone: 
+ newListFromFile: 

+ newListFromFile:zone: 

+ newListFromStream: 

+ newListFromStream:zone: 

Copying and freeing an NXEPSImageRep 

- copy 

- free 

Getting the rectangle that bounds the image 

- getBoundingBox: 
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Getting image data 


getEPSrlength: 


Drawing the image - prepareGState 

- drawln: 

- draw 

Archiving - read: 

- write: 

newListFromFile: 

+ (List *)newListFromFile:(const char *) filename 

Creates one new NXEPSImageRep instance for each EPS image specified in the 
filename file, and returns a List object containing all the objects created. If no 
NXEPSImageReps can be created (for example, if filename doesn’t exist or doesn’t 
contain EPS code), nil is returned. The List should be freed when it’s no longer needed. 

Each new NXEPSImageRep is initialized by the initFromFile: method, which reads a 
minimal amount of information about the image from the header comments in the file. 
The PostScript code will be read when it’s needed to render the image. 

See also: + newListFromFileizone:, - initFromFile: 
newListFromFile: zone: 

+ (List *)newListFromFile: (const char *) filename zone:(NXZone *)aZone 

Returns a List of new NXEPSImageRep instances, just as newListFromFile: does, 
except that the NXEPSImageReps and the List object are allocated from memory 
located in aZone. 

See also: + newListFromFile:, - initFromFile: 


newListFr omSection: 

+ (List *)newListFromSection: (const char *)name 

Creates one new NXEPSImageRep instance for each image specified in the name 

section of the_EPS segment in the executable file, and returns a List object containing 

all the objects created. If not even one NXEPSImageRep can be created (for example, 
if the name section doesn’t exist or doesn’t contain EPS code), nil is returned. The List 
should be freed when it’s no longer needed. 

Each new NXEPSImageRep is initialized by the initFromSection: method, which 
reads reads a minimal amount of information about the image from the EPS header 
comments. The PostScript code will be read only when it’s needed to render the image. 

See also: + newListFromSection:zone:, - initFromSection: 
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newListFromSection:zone: 

+ (List *)newListFromSection: (const char *)name zone:(NXZone *)aZone 

Returns a List of new NXEPSImageRep instances, just as newListFromSection: does, 
except that the List object and the NXEPSImageReps are allocated from memory 
located in aZone. 

See also: + newListFromSection:, - initFromSection: 
newListFromStream: 

+ (List *)newListFromStream:(NXStream *)stream 

Creates one new NXEPSImageRep instance for each EPS image that can be read from 
stream, and returns a List object containing all the objects created. If not even one 
NXEPSImageRep can be created (for example, if the stream doesn’t contain EPS 
code), nil is returned. The List should be freed when it’s no longer needed. 

The data is read and each new object initialized by the initFromStream: method. 

See also: + newListFromStream: zone:, - initFrom Stream: 

newListFromStream:zone: 

+ (List *)newListFromStream:(NXStream *)stream zone:(NXZone *)aZone 

Returns a List of new NXEPSImageRep instances, just as newListFromStream: does, 
except that the List object and the NXEPSImageReps are allocated from memory 
located in aZone. 

See also: + newListFromStream:, - initFromStream: 


INSTANCE METHODS 


copy 

-copy 

Returns a new NXEPSImageRep instance that’s an exact copy of the receiver. The new 
object will have its own copy of the image data. It doesn’t need to be initialized. 
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draw 


- (BOOL)draw 

Draws the image at (0.0, 0.0) in the current coordinate system on the current device. 
This method returns YES if successful in rendering the image, and NO if not. 

An NXEPSImageRep draws in a separate PostScript context and graphics state. Before 
the EPS code is interpreted, all graphics state parameters—with the exception of the 
CTM and device—are set to the Window Server’s defaults and the defaults required by 
EPS conventions. If you want to change any of these defaults, you can do so by 
implementing a prepareGState method in an NXEPSImageRep subclass. The draw 
method invokes prepareGState just before sending the EPS code to the Window 
Server. For example, if you need to set a transfer function or halftone screen that’s 
specific to the image, prepareGState is the place to do it. 

See also: - drawAt: (NXImageRep), - drawln:, - prepareGState 
drawln: 

- (BOOL)drawIn:(const NXRect *)rect 

Draws the image so that it fits inside the rectangle referred to by rect. The current 
coordinate system is translated and scaled so the image will appear at the right location 
and fit within the rectangle. The draw method is then invoked to produce the image. 
This method passes through the return value of the draw method, which indicates 
whether the image was successfully drawn. 

The coordinate system is not restored after it has been altered. 

See also: - draw, - drawAt: (NXImageRep) 

free 

- free 

Deallocates the NXEPSImageRep. 

getBoundingBox: 

- getBoundingBox: (NXRect *)theRect 

Provides the rectangle that bounds the image. The rectangle is copied from the 
“%%BoundingBox:” comment in the EPS header to structure referred to by theRect. 
Returns self. 
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getEPS: length: 

- getEPS:(char **)theEPS length:(int *)numBytes 

Sets the pointer referred to by theEPS so that it points to the EPS code. The length of 
the code in bytes is provided in the integer referred to by numBytes. Returns self. 


init 


Generates an error message. This method can’t be used to initialize an 
NXEPSImageRep. Use one of the other init... methods instead. 

See also: - initFromSection:, - initFromFile:, - initFromStream: 
initFromFile: 

- initFromFile:(const char *)j filename 

Initializes the receiver, a newly allocated NXEPSImageRep object, with the EPS image 
found in the filename file. Some information about the image is read from the EPS 
header comments, but the PostScript code won’t be read until it’s needed to render the 
image. 

If the new object can’t be initialized for any reason (for example, filename doesn’t exist 
or doesn’t contain EPS code), this method frees it and returns nil. Otherwise, it returns 
self. 

This method is the designated initializer for NXEPSImageReps that read EPS code 
from a file. 

See also: + newListFromFile:, - initFromSection: 
initFromSection: 

- initFromSection: (const char *)name t 

Initializes the receiver, a newly allocated NXEPSImageRep object, with the image 

found in the name section in the_EPS segment of the application executable. Some 

information about the image is read from the EPS header comments, but the PostScript 
code won’t be read until it’s needed to render the image. 

If the new object can’t be initialized for any reason (for example, the name section 
doesn’t exist or doesn’t contain EPS code), this method frees it and returns nil. 
Otherwise, it returns self. 

This method is the designated initializer for NXEPSImageReps that read image data 
from the_EPS segment.. 

See also: + newListFromSection:, - initFromFile: 
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initFromStream: 


- initFromStream: (NXStream *)stream 

Initializes the receiver, a newly allocated NXEPSImageRep object, with the EPS image 
read from stream. If the new object can’t be initialized for any reason (for example, 
stream doesn’t contain EPS code), this method frees it and returns nil. Otherwise, it 
returns self. 

This method is the designated initializer for NXEPSImageReps that read image data 
from a stream. 

See also: + newListFromStream: 

prepareGState 

- prepareGState 

Implemented by subclasses to initialize the graphics state before the image is drawn. 
The draw method sends a prepareGState message just before rendering the EPS code. 
This default implementation of the method does no initialization; it simply returns self. 

See also: - draw 

read: 

- read:(NXTypedStream *)stream 

Reads the NXEPSImageRep from the typed stream stream. 

See also: - write: 

write: 

- write: (NXTypedStream *)stream 

Writes the NXEPSImageRep to the typed stream stream. 

See also: - read: 
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NXImage 

INHERITS FROM Object 

DECLARED IN appkit/NXImage.h 

CLASS DESCRIPTION 

An NXImage object contains an image that can be composited anywhere without first 
being drawn in any particular View. It manages the image by: 

• Reading image data from the_ICON,_TIFF, or_EPS segments of the 

application executable, from a separate file, or from an NXStream. 

• Keeping multiple representations of the same image. 

• Choosing the representation that’s appropriate for any given display device. 

• Caching the representations it uses by rendering them in off-screen windows. 

• Optionally retaining the data used to draw the representations, so that they can be 
reproduced when needed. 

• Compositing the image from the off-screen cache to where it’s needed on-screen. 

• Reproducing the image for the printer so that it matches what’s displayed 
on-screen, yet is the best representation possible for the printed page. 


Defining an Image 

An image can be created from various types of data: 

• Encapsulated PostScript code (EPS) 

• Bitmap data in Tag Image File Format (TIFF) 

• Untagged (raw) bitmap data 

If TIFF or EPS image data is placed in a section of the application executable or in a 
separate file, the NXImage object can access the data whenever it’s needed to create the 
image. If TIFF or EPS data is read from a stream, the NXImage object may need to 
retain the data itself. 
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Images can also be defined by the program, in two ways: 

• By drawing the image in an off-screen window maintained by the NXImage object. 
In this case, the NXImage maintains only the cached image. 

• By defining a method that can be used to draw the image when needed. This allows 
the NXImage to delegate responsibility for producing the image to some other 
object. 


Image Representations 

An NXImage object can keep more than one representation of an image. Multiple 
representations permit the image to be customized for the display device. For example, 
different hand-tuned TIFF images can be provided for monochrome and color screens, 
and an EPS representation or a custom method might be used for printing. All 
representations are versions of the same image. 

An NXImage returns a List of its representations in response to a representationList 
message. Each representation is a kind of NXImageRep object: 


NXEPSImageRep An image that can be recreated from EPS data that’s either 
retained by the object or at a known location in the file 
system. 

NXBitmapImageRep An image that can be recreated from bitmap or TIFF data. 


NXCustomlmageRep 


An image that can be redrawn by a method defined in the 
application. 


NXCachedlmageRep An image that has been rendered in an off-screen cache 
from data or instructions that are no longer available. The 
image in the cache provides the only data from which the 
image can be reproduced. 


You can also define other NXImageRep subclasses for objects that render images from 
other kinds of source information. 


Choosing and Caching Representations 

The NXImage object will choose the representation that best matches the rendering 
device. By default, the choice is made according to the following set of ordered rules. 
Each rule is applied in turn until the choice of representation is narrowed to one: 

6. Choose a color representation for a color device, and a gray-scale representation for 
a monochrome device. 
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7. Choose a representation with a resolution that matches the resolution of the device, 
or if no representation matches, choose the one with the highest resolution. 

By default, any image representation with a resolution that’s an integer multiple of 
the device resolution is considered to match. If more than one representation 
matches, the NXImage will choose the one that’s closest to the device resolution. 
However, you can force resolution matches to be exact by passing NO to the 

setMatchedOnMultipleResolution: method. 

Rule 2 prefers TIFF and bitmap representations, which have a defined resolution, 
over EPS representations, which don’t. However, you can use the 
setEPSPreferredOnResolutionMismatch: method to have the NXImage choose 
an EPS representation in case a resolution match isn’t possible. 

8. If all else fails, choose the representation with a specified bits per sample that 
matches the depth of the device. If no representation matches, choose the one with 
the highest bits per sample. 

By passing NO to the setColorMatchPreferred: method, you can have the NXImage 
try for a resolution match before a color match. This essentially inverts the first and 
second rules above. 

When first asked to composite the image, the NXImage object chooses the 
representation that’s best for the destination display device. It renders the 
representation in an off-screen window on the same device, then composites it from this 
cache to the desired location. Subsequent requests to composite the image use the same 
cache. Representations aren’t cached until they’re needed for compositing. 

When printing, the NXImage tries not to use the cached image. Instead, it attempts to 
render on the printer—using the appropriate EPS or TIFF data, or a delegated 
method—the best version of the image that it can. Only as a last resort will it image 
the cached bitmap. 


Image Size 

Before an NXImage can be used, the size of the image must be set, in units of the base 
coordinate system. If a representation is smaller or larger than the specified size, it can 
be scaled to fit. 

If the size of the image hasn’t already been set when the NXImage is provided with an 
EPS or TIFF representation, the size will be set from the EPS or TIFF data. The EPS 
bounding box and TIFF “ImageLength” and “ImageWidth” fields specify an image 
size. 
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Coordinate Systems 

Images have the horizontal and vertical orientation of the base coordinate system; they 
can’t be rotated or flipped. When composited, an image maintains this orientation, no 
matter what coordinate system it’s composited to. (The destination coordinate system 
is used only to determine the location of a composited image, not its size or 
orientation.) 

It’s possible to refer to portions of an image when compositing (or when defining 
subimages), by specifying a rectangle in the image’s coordinate system, which is 
identical to the base coordinate system, except that the origin is at the lower left comer 
of the image. 


Named Images 

An NXImage object can be identified either by its id or by a name. Assigning an 
NXImage a name adds it to a database kept by the class object; each name in the 
database identifies one and only one instance of the class. When you ask for an 
NXImage object by name (with the findlmageNamed: method), the class object 
returns the one from its database, which also includes all the system bitmaps provided 
by the Application Kit. If there’s no object in the database for the specified name, the 

class object tries to create one by looking in the_ICON,_EPS, and_TIFF segments 

of the application’s executable file, and then in the directory of the executable file (the 
file package). 

If a section or file matches the name, an NXImage is created from the data stored there. 
You can therefore create NXImage objects simply by including EPS or TIFF data for 
them within the executable file, or in files inside the application’s file package. 

The job of displaying an image within a View can be entrusted to a Cell object. A Cell 
identifies the image it’s to display by the name of the NXImage object. The following 
code sets my Cell to display one of the system bitmaps: 

id myCell = [[Cell alloc] initlconCell:"NXswitch"]; 


INSTANCE VARIABLES 
Inherited from Object 
Declared in NXImage 
name 


Class isa; 

char *name; 

The name assigned to the image. 
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METHOD TYPES 


Initializing a new NXImage instance 

- init 

- initSize: 

- initFromSection: 

- initFromFile: 

- initFromStream: 

- initFromlmagerrect: 

Freeing an NXImage object - free 

Setting the size of the image - setSize: 

- getSize: 

Referring to images by name - setName: 

- name 

+ findlmageNamed: 

Specifying the image - useDrawMethod:inObject: 

- useFromSection: 

- useFromFile: 

- useRepresentation: 

- useCacheWithDepth: 

- loadFromStream: 

- lockFocus 

- lockFocusOn: 

- unlockFocus 

Using the image - composite:toPoint: 

- composite:fromRect:toPoint: 

- dissolve:toPoint: 

- dissolve:fromRect:toPoint: 

Choosing which image representation to use 

- setColorMatchPreferred: 

- isColorMatchPreferred 

- setEPSUsedOnResolutionMismatch: 

- isEPSUsedOnResolutionMismatch 

- setMatchedOnMultipleResolution: 

- isMatchedOnMultipleResolution 

Getting the representations - lastRepresentation 

- bestRepresentation 

- representationList 

- removeRepresentation: 
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Determining how the image is stored 



- setUnique: 

- isUnique 

- setDataRetained: 

- isDataRetained 

- setCacheDepthBounded: 

- isCacheDepthBounded 

- getlmage:rect: 

Determining how the image is drawn 

- setFlipped: 

- isFlipped 

- setScalable: 

- isScalable 

- setBackgroundColor: 

- backgroundColor 

- drawRepresentation:inRect: 

- recache 

Assigning a delegate 

- setDelegate: 

- delegate 

Producing TIFF data for the image 

- writeTIFF: 

- writeTIFF:allRepresentations: 

Archiving 

- read: 

- write: 

- finishUnarchiving 


CLASS METHODS 

findlmageNamed: 

+ findlmageNamed: (const char *)name 

Returns the NXImage instance associated with name. The returned object can be: 

• One that’s been assigned a name with the setName: method, 

• One of the named system bitmaps provided by the Application Kit, or 

• One that’s been created and named by this method. 

If there’s no known NXImage with name, this method tries to create one by searching 

for image data in the_ICON,_EPS, and_TIFF segments of the application 

executable and in the directory (file package) where the executable resides: 

1. It looks first in the_ICON segment for a name section containing either 

Encapsulated PostScript code (EPS) or Tag Image File Format (TIFF) data. 
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2. Failing to find image data there, it looks next for a section with TIFF data in the 

_TIFF segment if name includes a “.tiff’ extension, or for a section containing 

EPS data in the_EPS segment if name includes a “.eps” extension. If name has 

neither extension, both segments are searched, first after adding the appropriate 
extension to name, then for name alone, without an extension. If it finds sections 
in both segments, it creates both EPS and TIFF representations of the image. 

3. If this method can’t find a EPS or TIFF representation in any segment, it searches 
for name.e ps and name .tiff files in the directory containing the application 
executable (the file package). This allows you to keep image data in separate files 
during the development phase (so that you won’t have to relink every time the 
image changes), then later insert the data in a segment of the finished executable. 

If a section or file contains data for more than one image, a separate representation is 
created for each one. If an image representation can’t be found for name, no object is 
created and nil is returned. 

The preferred way to name an EPS or TIFF image is to ask for a name without the 
“.eps” or “.tiff’ extension, but to include the extension on the section name or file name. 

This method treats all images found in the_ICON segment as application or document 

icons, since the point of putting an image in that segment rather than in_TIFF or 

_EPS is to advertise it to the Workspace Manager. The Workspace Manager requires 

icons to be no more than 48 pixels wide by 48 pixels high. Therefore, an NXImage 
created from an_ICON section has its size set to 48.0 by 48.0 and is made scalable. 

See also: - setName:, - name 


INSTANCE METHODS 


backgroundColor 

- (NXColor)backgroundColor 

Returns the background color of the rectangle where the image is cached. If no 
background color has been specified, NX_COLORCLEAR is returned, indicating a 
totally transparent background. 

The background color will be visible when the image is composited only if the image 
doesn’t completely cover all the pixels within the area specified for its size. 

See also: - setBackgroundColor: 
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bestRepresentation 

- (NXImageRep *)bestRepresentation 

Returns the image representation that best matches the display device with the deepest 
frame buffer currently available to the Window Server. 

See also: - representationList 

composite:fromRect:toPoint: 

- composite: (in t)<?/? 

fromRect: (const NXRect *)aRect 
toPoint: (const NXPoint *)aPoint 

Composites the area enclosed by the aRect rectangle to the location specified by aPoint 
in the current coordinate system. The op and aPoint arguments are the same as for 
compositertoPoint:. The source rectangle is specified relative to a coordinate system 
that has its origin at the lower left comer of the image, but is otherwise the same as the 
base coordinate system. 

This method doesn’t check to be sure that the rectangle encloses only portions of the 
image. Therefore, it can conceivably composite areas that don’t properly belong to the 
image, if the aRect rectangle happens to include them. If this turns out to be a problem, 
you can prevent it from happening by having the NXImage cache its representations in 
their own individual windows (with the setUnique: method). The window’s clipping 
path will prevent anything but the image from being composited. 

Compositing part of an image is as efficient as compositing the whole image, but 
printing just part of an image is not. When printing, it’s necessary to draw the whole 
image and rely on a clipping path to be sure that only the desired portion appears. 

If successful in compositing (or printing) the image, this method returns self. If not, it 
returns nil. 

See also: - compositertoPoint:, - setUnique: 


compositertoPoint: 

- composite :fimt)op toPoint:(const NXPoint *)aPoint 

Composites the image to the location specified by aPoint. The first argument, op, 
names the type of compositing operation requested. It should be one of the following 
constants: 


NX_CLEAR 

NX_COPY 

NX_PLUSD 

NX_PLUSL 


NX_SOVER 

NX_SIN 

NX_SOUT 

NX_SATOP 


NX_DOVER NX_XOR 

NXJDIN 

NX_DOUT 

NX_DATOP 


2-392 Chapter 2: Class Specifications 



aPoint is specified in the current coordinate system—the coordinate system of the 
currently focused View—and designates where the lower left comer of the image will 
appear. The image will have the orientation of the base coordinate system, regardless 
of the destination coordinates. 

The image is composited from its off-screen window cache. Since the cache isn’t 
created until the image representation is first used, this method may need to render the 
image before compositing. 

When printing, the compositing methods do not composite, but attempt to render the 
same image on the page that compositing would render on the screen, choosing the best 
available representation for the printer. The op argument is ignored. 

If successful in compositing (or printing) the image, this method returns self. If not, it 
returns nil. 

See also: - composite:fromRect:toPoint:, - dissolve:toPoint: 

delegate 

- delegate 

Returns the delegate of the NXImage object, or nil if no delegate has been set. 

See also: - setDelegate: 

dissolve:fromRect:toPoint: 

- dissolve: (fioat)de Ita 

fromRect: (const NXRect *)aRect 
toPoint: (const NXPoint *)aPoint 

Composites the aRect portion of the image to the location specified by aPoint, just as 
composite:fromRect:toPoint: does, but uses the dissolve operator rather than 
composite, delta is a fraction between 0.0 and 1.0 that specifies how much of the 
resulting composite will come from the NXImage. 

When printing, this method is identical to composite:fromRect:toPoint:. The delta 
argument is ignored. 

If successful in compositing (or printing) the image, this method returns self. If not, it 
returns nil. 

See also: - dissolve:toPoint:, - composite:fromRect:toPoint: 


Application Kit Classes: NXImage 


2-393 



dissolveitoPoint: 

- dissolve :(float)de Ita toPoint:(const NXPoint *)aPoint 

Composites the image to the location specified by aPoint, just as composite:toPoint: 
does, but uses the dissolve operator rather than composite, delta is a fraction between 
0.0 and 1.0 that specifies how much of the resulting composite will come from the 
NXImage. 

To slowly dissolve one image into another, this method (or 
dissolve:fromRect:toPoint:) needs to be invoked repeatedly with an ever-increasing 
delta. Since delta refers to the fraction of the source image that’s combined with the 
original destination (not the destination image after some of the source has been 
dissolved into it), the destination image should be replaced with the original destination 
before each invocation. This is best done in a buffered window before the results of the 
composite are flushed to the screen. 

When printing, this method is identical to composite:toPoint:. The delta argument is 
ignored. 

If successful in compositing (or printing) the image, this method returns self. If not, it 
returns nil. 

See also: - dissolve:fromRect:toPoint:, - composite:toPoint: 

drawRepr esentation: inRect: 

- (BOOL)drawRepresentation:(NXImageRep *)imageRep 

inRect: (const NXRect *)rect 

Fills the specified rectangle with the background color, then sends the imageRep a 
drawln: message to draw itself inside the rectangle (if the NXImage is scalable), or a 
draw At: message to draw itself at the location of the rectangle (if the NXImage is not 
scalable). The rectangle is located in the current window and is specified in the current 
coordinate system. 

This method is not ordinarily used in program code; the NXImage uses it to cache its 
representations and to print them. By overriding it in a subclass, you can change how 
representations appear in the cache, and thus how they’ll appear when composited. For 
example, you could scale or rotate the coordinate system, then send a message to super 
to perform this version of the method. 

This method passes through the return of the drawln: or draw At: method, which 
indicates whether or not the representation was successfully drawn. When NO is 
returned, the NXImage will ask another representation, if there is one, to draw the 
image. 

If the background color is fully transparent and the image is not being cached by the 
NXImage, the rectangle won’t be filled before the representation draws. 

See also: - drawln (NXImageRep), - draw At: (NXImageRep) 
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finishUnarchiving 

- finishUnarchiving 

Registers the name of the newly unarchived receiver, if it has a name, and returns nil. 
It also returns nil if the receiving NXImage doesn’t have a name. However, if the 
receiver has a name that can’t be registered because it’s already in use, this method frees 
the receiver and returns the existing NXImage with that name, thus replacing the 
unarchived object with one that’s already in use. 

finishUnarchiving messages are generated automatically (by NXReadObjectO) after 
the object has be unarchived (by read:) and initialized (by awake). 

free 

- free 

Deallocates the NXImage and all its representations. If the object had been assigned a 
name, the name is removed from the class database. 

getlmage:rect: 

- getlmage: (NXImage **)thelmage rect:(NXRect *)theRect 

Provides information about the receiving NXImage object, if it’s a subimage of another 
NXImage. The parent NXImage is assigned to the variable referred to by thelmage, 
and the rectangle where the receiver is located in that NXImage is copied into the 
structure referred to by theRect. 

If the receiver is not a subimage of another NXImage object (if it wasn’t initialized by 
initFromImage:rect:), the variable referred to by thelmage is set to nil and the 
rectangle is not modified. 

Returns self. 

See also: - initFromImage:rect: 
getSize: 

- getSize:(NXSize *)theSize 

Copies the size of the image into the structure specified by theSize. If no size has been 
set, all values in the structure will be set to 0.0. Returns self. 

See also: - setSize: 
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init 


- init 


Initializes the receiver, a newly allocated NXImage instance, but does not set the size 
of the image. The size must be set, and at least one image representation provided, 
before the NXImage object can be used. The size can be set either through a setSize: 
message or by providing an image from data (EPS or TIFF) that specifies a size. 

See also: - initSize:, - setSize: 
initFromFile: 

- initFromFile:(const char *)filename 

Initializes the receiver, a newly allocated NXImage instance, with the image specified 
in filename , which can be a full or relative pathname. The file should contain EPS or 
TIFF data for one or more versions of the image. An image representation will be 
created and added to the NXImage for each image specified. The size of the NXImage 
is set from information found in the TIFF fields or the EPS bounding box comment. 

After finishing the initialization, this method returns self. However, if the new instance 
can’t be initialized, it’s freed and nil is returned. 

This method invokes the useFromFile: method to find filename and create 
representations for the NXImage. It’s equivalent to a combination of init and 
useFromFile:. 

See also: - useFromFile:, — initSize: 

initFr omlmage: r ect: 

- initFromlmage: (NXImage *)image rect:(const NXRect *)rect 

Initializes the receiver, a newly allocated NXImage instance, so that it’s a subimage for 
the rect portion of another NXImage object, image. The size of the new object is set 
from the size of the rect rectangle. Returns self. 

Once initialized, the new instance can’t be altered and will remain dependent on the 
original image. Changes made to the original will also change the subimage. 

Subimages should be used only as a way of avoiding composite:fromRect:toPoint: 
and dissolve:fromRect:toPoint: messages. They permit you to divide a large image 
into sections and assign each section a name. The name can then be passed to those 
Button and Cell methods that identify images by name rather than id. 

See also: - getlmage:rect:, - initSize: 
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initFromSection: 


- initFromSection: (const char *)name 

Initializes the receiver, a newly allocated NXImage instance, with the image specified 

in the name section of the_EPS or_TIFF segment of the application executable. If 

the section contains EPS or TIFF data for more than one version of the image, a 
representation will be created and added to the NXImage for each image specified. The 
size of the NXImage is set from information taken from the TIFF fields or the EPS 
bounding box comment. 

After finishing the initialization, this method returns self. However, if the new instance 
can’t be initialized, it’s freed and nil is returned. 

This method uses the useFromSection: method to find the name section and create 
representations for the NXImage. It’s equivalent to a combination of init and 
useFromFile:. 

See also: - useFromSection:, - initSize: 
initFromStream: 

- initFromStream:(NXStream *)stream 

Initializes the receiver, a newly allocated NXImage instance, with the image or images 
specified in the data read from stream , and returns self. If the receiver can’t be 
initialized for any reason, it’s freed and nil is returned. 

Since this method must store the data read from the stream or render the specified 
image immediately, it’s less preferred than initFromSection: or initFromFile:, which 
can wait until the image is needed. 

The stream should contain recognizable image data, either EPS or TIFF. It’s read using 
the loadFromStream: method, which will set the size of the NXImage from 
information found in the TIFF fields or the EPS bounding box comment. This method 
is equivalent to a combination of init and loadFromStream:. 

See also: - loadFromStream:, - initSize: 


Application Kit Classes: NXImage 


2-397 



initSize: 


- initSize: (const NXSize *)aSize 

Initializes the receiver, a newly allocated NXImage instance, to the size specified and 
returns self. The size should be specified in units of the base coordinate system. It must 
be set before the NXImage can be used. 

This method is the designated initializer for the class (the method that incorporates the 
initialization of classes higher in the hierarchy through a message to super). All other 
init... methods defined in this class work through this method. 

See also: - setSize: 

isCacheDepthBounded 

- (BOOL)isCacheDepthBounded 

Returns YES if the depth of the off-screen windows where the NXImage’s 
representations are cached are bounded by the application’s default depth limit, and NO 
if the depth of the caches can exceed that limit. The default is YES. 

See also: - setCacheDepthBounded:, + defaultDepthLimit (Window) 
isColorMatchPreferred 

Returns YES if, when selecting the representation it will use, the NXImage first looks 
for one that matches the color capability of the rendering device (choosing a gray-scale 
representation for a monochrome device and a color representation for a color device), 
then if necessary narrows the selection by looking for one that matches the resolution 
of the device. If the return is NO, the NXImage first looks for a representation that 
matches the resolution of the device, then tries to match the representation to the color 
capability of the device. The default is YES. 

See also: - setColorMatchPreferred: 

isDataRetained 

- (BOOL)isDataRetained 

Returns YES if the NXImage retains the data needed to render the image, and NO if it 
doesn’t. The default is NO. If the data is available in a section of the application 
executable or in a file that won’t be moved or deleted, or if responsibility for drawing 
the image is delegated to another object with a custom method, there’s no reason for the 
NXImage to retain the data. However, if the NXImage reads image data from a stream, 
you may want to have it keep the data itself. 

See also: - setDataRetained:, - loadFromStream: 
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isEPSUsedOnResolutionMismatch 


- (BOOL)isEPSUsedOnResolutionMismatch 

Returns YES if an EPS representation of the image should be used whenever it’s 
impossible to match the resolution of the device to the resolution of another 
representation of the image (a TIFF representation, for example). By default, this 
method returns NO to indicate that EPS representations are not necessarily preferred. 

See also: - setEPSUsedOnResolutionMismatch: 

isFlipped 

- (BOOL)isFlipped 

Returns YES if a flipped coordinate system is used when drawing the image, and NO 
if it isn’t. The default is NO. 

See also: - setFlipped: 

isMatchedOnMultipleResolution 

- (BOOL)isMatchedOnMultipIeResolution 

Returns YES if the resolution of the device and the resolution specified for the image 
are considered to match if one is a multiple of the other, and NO if device and image 
resolutions are considered to match only if they are exactly the same. The default is 
YES. 

See also: - setMatchedOnMultipleResolution: 

isScalable 

- (BOOL)isScalable 

Returns YES if image representations are scaled to fit the size specified for the 
NXImage. If representations are not scalable, this method returns NO. The default is 
NO. 

Representations created from data that specifies a size (for example, the 
“ImageLength” and “ImageWidth” fields of a TIFF representation or the bounding box 
of an EPS representation) will have the size the data specifies, which may differ from 
the size of the NXImage. 

See also: - setScalable: 
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isUnique 

- (BOOL)isUnique 

Returns YES if each representation of the image is cached alone in an off-screen 
window of its own, and NO if they can be cached in off-screen windows together with 
other images. A return of NO doesn’t mean that the windows are, in fact, shared, just 
that they can be. The default is NO. 

See also: -setUnique: 

lastRepresentation 

- (NXImageRep *)lastRepresentation 

Returns the last representation that was specified for the image (the last one added with 
methods like useCacheWithDepth:, loadFromStream:, and initFromStream:). If 
the NXImage has no representations, this method returns nil. 

See also: - representationList, - bestRepresentation 
loadFromStream: 

- (BOOL)loadFromStream:(NXStream *)stream 

Creates an image representation from the data read from stream and adds it to the 
receiving NXImage’s list of representations. The data must be of a recognizable type, 
either TIFF or EPS. If the size of the NXImage hasn’t yet been set, it will be set from 
information found in the TIFF fields or from the EPS bounding box comment. If the 
stream contains data specifying more than one image, a separate representation is 
created for each one. 

If the NXImage object doesn’t retain image data (isDataRetained returns NO), the 
image will be rendered in an off-screen window and the representations will be of type 
NXCachedlmageRep. If the data is retained, the representations will be of type 
NXBitmapImageRep or NXEPSImageRep, depending on the data. 

If successful in creating at least one representation, this method returns YES. If not, it 
returns NO. 

See also: - initFromStream: 
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lockFocus 


- (BOOL)lockFocus 

Focuses on the best representation for the NXImage, by making the off-screen window 
where the representation will be cached the current window and a coordinate system 
specific to the area where the image will be drawn the current coordinate system. The 
best representation is the one that best matches the deepest available frame buffer; it’s 
the same object returned by the bestRepresentation method. 

If the NXImage has no representations, lockFocus creates one with the 
useCacheWithDepth: method, specifying the best depth for the deepest frame buffer 
currently in use. To add additional representations, useCacheWithDepth: messages 
must be sent explicitly. 

This method returns YES if it’s successful in focusing on the representation, and NO if 
not. A successful lockFocus message must be balanced by a subsequent unlockFocus 
message to the same NXImage. These messages bracket the code that draws the image. 

If lockFocus returns NO, it will not have altered the current graphics state and should 
not be balanced by an unlockFocus message. 

See also: - lockFocusOn:, - lockFocus (View), - unlockFocus, 

- useCacheWithDepth:, - bestRepresentation 

lockFocusOn: 

- (BOOL)lockFocusOn:(NXImageRep *)imageRep 

Focuses on the imageRep representation, by making the off-screen window where it 
will be cached the current window and a coordinate system specific to the area where 
the image will be drawn the current coordinate system. 

This method returns YES if it’s successful in focusing on the representation, and NO if 
it’s not. A successful lockFocusOn: message must be balanced by a subsequent 
unlockFocus message to the same receiver. These messages bracket the code that 
draws the image. The useCacheWithDepth: method will add a representation 
specifically for this purpose. For example: 


[myNXImage useCacheWithDepth:NX_TwoBitGrayDepth]; 

if ( [myNXImage lockFocusOn:[myImage lastRepresentation]] ) { 

/* drawing code goes here */ 

[myNXImage unlockFocus]; 

} 

If lockFocusOn: returns NO, it will not have altered the current graphics state and 
should not be balanced by an unlockFocus message. 

See also: - lockFocus, - lockFocus (View), - unlockFocus, - lastRepresentation 
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name 


- (const char *)name 

Returns the name assigned to the NXImage, or NULL if no name has been assigned. 
See also: - setName:, + findlmageNamed: 

read: 

- read:(NXTypedStream *)stream 

Reads the NXImage and all its representations from the typed stream stream. 

See also: - write: 

recache 

- recache 

Invalidates the off-screen caches of all representations and frees them. The next time 
any representation is composited, it will first be asked to redraw itself in the cache. 
NXCachedlmageReps are not destroyed by this method. 

If an image is likely not to be used again, it’s a good idea to free its caches, since that 
will reduce that amount of memory consumed by your program and therefore improve 
performance. 

Returns self. 

removeRepresentation: 

- removeRepresentation :(NXImageRep *)imageRep 

Frees the imageRep representation after removing it from the NXImage’s list of 
representations. Returns self. 

See also: - representationList 

representationList 

- (List *)representationList 

Returns the List object containing all the representations of the image. The List 
belongs to the NXImage object, and there’s no guarantee that the same List object will 
be returned each time. Therefore, rather than saving the object that’s returned, you 
should ask for it each time you need it. 

See also: - bestRepresentation, - lastRepresentation 
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setBackgroundColor: 

- setBackgroundColor :(NXColor )aColor 

Sets the background color of the image. The default is NX_COLORCLEAR, 
indicating a totally transparent background. The background color will be visible only 
for representations that don’t touch all the pixels within the image when drawing. 
Returns self. 

See also: - backgroundColor 

setCacheDepthBounded: 

- setCacheDepthBounded :(BOOL )flag 

Determines whether the depth of the off-screen windows where the NXImage’s 
representations are cached should be limited by the application’s default depth limit. If 
flag is NO, window depths will be determined by the specifications of the 
representations, rather than by the current display devices. The default is YES. Returns 
self. 

See also: - isCacheDepthBounded, + defaultDepthLimit (Window) 

setColorMatchPreferred: 

- setColorMatchPreferred :(BOOL )flag 

Determines how the NXImage will select which representation to use. If flag is YES, 
it first tries to match the representation to the color capability of the rendering device 
(choosing a color representation for a color device and a gray-scale representation for 
a monochrome device), and then if necessary narrows the selection by trying to match 
the resolution of the representation to the resolution of the device. If flag is NO, the 
NXImage first tries to match the representation to the resolution of the device, and then 
tries to match it to the color capability of the device. The default is YES. Returns self. 

See also: - isColorMatchPreferred 

setDataRetained: 

- setDataRetained: (BOOL)flag 

Determines whether the NXImage retains the data needed to render the image. The 
default is NO. If the data is available in a section of the application executable or in a 
file that won’t be moved or deleted, or if responsibility for drawing the image is 
delegated to another object with a custom method, there’s no reason for the NXImage 
to retain the data. However, if the NXImage reads image data from a stream, you may 
want to have it keep the data itself. 

See also: - isDataRetained 
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setDelegate: 

- setDelegateianObject 

Makes anObject the delegate of the NXImage. Returns self. 

See also: - delegate 

setEPSUsedOnResolutionMismatch: 

- setEPSUsedOnResolutionMismatch:(BOOL)//ag 

Determines whether EPS representations will be preferred when there are no 
representations that match the resolution of the device. The default is NO. Returns 
self. 

See also: - isEPSUsedOnResolutionMismatch 
setFlipped: 

- setFlipped:(BOOL )flag 

Determines whether the polarity of the y-axis is inverted when drawing an image. If 
flag is YES, the image will have its coordinate origin in the upper left comer and the 
positive y-axis will extend downward. This method affects only the coordinate system 
used to draw the image, whether through a method assigned with the 
useDrawMethodiobject: method or directly by focusing on a representation. It 
doesn’t affect the coordinate system for specifying portions of the image for methods 
like composite:fromRect:toPoint: or initFromlmagerrect:. 

See also: - isFlipped 

setMatchedOnMultipleResolution: 

- setMatchedOnMultipleResolution: (BOOL)flag 

Determines whether image representations with resolutions that are exact multiples of 
the resolution of the device are considered to match the device. The default is NO. 
Returns self. 

See also: - isMatchedOnMultipleResolution 
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setName: 


- (BOOL)setName:(const char *)string 

Sets string to be the name of the NXImage object and registers it under that name. If 
the object already has a name, that name is discarded. If string is already the name of 
another object or if the receiving NXImage is one of the system bitmaps provided by 
the Application Kit, the assignment fails. 

If successful in naming or renaming the receiver, this method returns YES. Otherwise 
it returns NO. 

See also: + findlmageNamed:, - name 

setScalable: 

- setScalable: (BOOL )flag 

Determines whether representations with sizes that differ from the size of the NXImage 
will be scaled to fit. The default is NO. 

Generally, representations that are created through NXImage methods (such as 
useCacheWithDepth: or initFromSection:) have the same size as the NXImage. 
However, a representation that’s added with the useRepresentation: method may have 
a different size, and representations created from data that specifies a size (for example, 
the “ImageLength” and “ImageWidth” fields of a TIFF representation or the bounding 
box of an EPS representation) will have the size specified. 

Returns self. 

See also: - isScalable 

setSize: 

- setSize: (const NXSize *)aSize 

Sets the width and height of the image. The size referred to by aSize should be in units 
of the base coordinate system. The size of an NXImage must be set before it can be 
used. Returns self. 

The size of an NXImage can be changed after it has been used, but changing it 
invalidates all its caches and frees them. When the image is next composited, the 
selected representation must draw itself in an off-screen window to recreate the cache. 

See also: - getSize:, - initSize: 
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setUnique: 

- setUnique: (BOOL)flag 

Determines whether each image representation will be cached in its own off-screen 
window or in a window shared with other images. If flag is YES, each representation 
is guaranteed to be in a separate window. If flag is NO, a representation can be cached 
together with other images, though in practice it might not be. The default is NO. 

If an NXImage is to be resized frequently, it’s more efficient to cache its representations 
in unique windows. 

This method does not invalidate any existing caches. Returns self. 

See also: -isUnique 

unlockFocus 

- unlockFocus 

Balances a previous lockFocus or IockFocusOn: message. All successful lockFocus 
and IockFocusOn: messages (those that return YES) must be followed by a subsequent 
unlockFocus message. Those that return NO should never be followed by 

unlockFocus. 

Returns self. 

See also: - lockFocus, - IockFocusOn: 
useCacheWithDepth: 

- (BOOL)useCache WithDepth: (NXWindowDepth)afe/?f/z 

Creates a representation of type NXCachedlmageRep and adds it to the NXImage’s list 
of representations. Initially, the representation is nothing more than an empty area 
equal to the size of the image in an off-screen window with the specified depth. You 
must focus on the representation and draw the image. The following code shows how 
an NXImage might be created with the same appearance as a View. 


id myImage/ 

NXRect theRect; 

[myView getFrame:StheRect]; 

mylmage = [[NXImage alloc] initSize:StheRect.size]; 
[mylmage useCacheWithDepth:NX_DefaultDepth] 
if ( [mylmage lockFocus] ) { 

[myView drawSelf:(NXRect *)0 :0] ; 

[mylmage unlockFocus]; 

} 
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depth should be one of the following enumerated values, defined in the header file 

appkit/graphics.h: 

NX_DefaultDepth 
NX_TwoBitGrayDepth 
NX_EightB itGrayDepth 
NX_TwelveBitRGBDepth 
NX_TwentyFourBitRGBDepth 

If successful in adding the representation, this method returns YES. If the size of the 
image has not been set or the cache can’t be created for any other reason, it returns NO. 

useDrawMethodiinObject: 

- (BOOL)useDrawMethod:(SEL)tfSe/ecfor inObject :anObject 

Creates a representation of type NXCustomlmageRep and adds it to the NXImage 
object’s list of representations. aSelector should name a method that can draw the 
image in the NXImage object’s coordinate system, and that takes a single argument, the 
id of the NXCustomlmageRep. anObject should be the id of an object that can perform 
the method. 

This type of representation allows you to delegate responsibility for creating an image 
to another object within the program. 

This method returns YES if it’s successful in creating the representation, and NO if it’s 
not. 

useFromFile: 

- (BOOL)useFromFile: (const char *)filename 

Creates an image representation from the data found in filename, which can be a full or 
relative path, and adds the representation to the receiving NXImage. The data must be 
of a recognizable type, either EPS or TIFF. If the size of the NXImage has not yet been 
set, it will be set from information found in the TIFF fields or from the EPS bounding 
box comment. 

If a representation can be added to the NXImage, this method returns YES. If not, it 
returns NO. In the current implementation, it may return YES even if the filename file 
doesn’t exist or it contains bad data. 

If filename contains data specifying more than one image, a separate representation is 
added for each one. 

See also: - initFromFile: 
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useFr omSection: 


- (BOOL)useFromSection: (const char *)name 

Creates an image representation from the data found in the name section of the_EPS 

or_TIFF segment of the application executable, and adds the representation to the 

NXImage. The data must be of a recognizable type, either EPS or TIFF. If the size of 
the NXImage has not yet been set, it will be set from information found in the TIFF 
fields or from the EPS bounding box comment. 

If name includes a ‘‘.tiff’ extension, this method looks in the_TIFF segment for a 

TIFF representation of the image; if name includes a “.eps” extension, it looks in the 

_EPS segment for an EPS representation. If name has neither extension, both 

segments are searched after adding the appropriate extension. Failing to find a section 
that matches the extended name, both segments are searched again for a section that 
matches name alone, without the extensions. 

If no section is found that matches name, with or without the extension, this method 
searches for nameXifi and name.eps files in the directory where the application 
executable resides. 

If sections that match the name are found in both the_EPS and_TIFF segments (or 

both “.eps” and ‘‘.tiff’ files are found), this method creates both EPS and TIFF 
representations for the image. If the data in a section or file specifies more than one 
image, a separate representation is created for each one. 

This method returns YES if a representation can be added to the NXImage, and NO if 
not. In the current implementation, it may return YES even if the section matching 
name contains bad data or no such section can be found. 

See also: - initFromSection: 
useRepr esentation: 

- (BOOL)useRepresentation:(NXImageRep *)imageRep 

Adds imageRep to the receiving NXImage object’s list of representations. If successful 
in adding the representation, this method returns YES. If not, it returns NO. 

Any representation that’s added by this method will belong to the NXImage and will 
be freed when the NXImage is freed. Representations can’t be shared among 
NXImages. 

See also: - representationList 
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write: 


- write :(NXTypedStream *)stream 

Writes the NXImage and all its representations to the typed stream stream. 
See also: - read: 


writeTIFF: 

- writeTIFF: (NXStream *)stream 

Writes TIFF data for the representation that best matches the display device with the 
deepest frame buffer to stream. This method is a shorthand for 
writeTIFF:allRepresentations: with a flag of NO. Returns self. 

writeTIFF:allRepresentations: 

- writeTIFF: (NXStream *)stream 

allRepresentations: (BOOL )flag 

Writes TIFF data for the representations to stream. If flag is YES, data will be written 
for each of the representations. If flag is NO, data will be written only for the 
representation that best matches the display device with the deepest frame buffer. 
Returns self. 

If stream is positioned anywhere but at the beginning of the stream, this method will 
append the representation(s) it writes to the TIFF data it assumes is already in the 
stream. To do this, it must be able to read the TIFF header from the stream. Therefore, 
the stream must be opened for NX_READWRITE permission. 


METHOD IMPLEMENTED BY THE DELEGATE 


imageDidNotDraw:inRect: 

- (NXImage *)imageDidNotDraw: sender inRect:(NXRect *)aRect 

Implemented by the delegate to respond to a message sent by the sender NXImage 
when the sender was unable, for whatever reason, to composite its image. The delegate 
can return another NXImage to draw in the sender's place. If not, it should return nil 
to indicate that sender should give up the attempt at drawing the image. 
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NXImageRep 

INHERITS FROM 
DECLARED IN 


Object 

appkit/NXImageRep.h 


CLASS DESCRIPTION 


NXImageRep is an abstract superclass for objects that know how to render an image. 
Each of its subclasses defines an object that can draw an image from a particular kind 
of source data. There are four subclasses defined in the Application Kit: 


Subclass 


Source Data 


NXBitmapImageRep 

NXEPSImageRep 

NXCustomlmageRep 

NXCachedlmageRep 


Tag Image File Format (TIFF) and other bitmap data 
Encapsulated PostScript code (EPS) 

A delegated method that can draw the image 
A rendered image, usually in an off-screen window 


An NXImageRep can be used simply to render an image, but is more typically used 
indirectly, through an NXImage object. An NXImage manages a group of 
representations, choosing the best one for the current output device. 


INSTANCE VARIABLES 
Inherited from Object 
Declared in NXImageRep 
size 


Class isa; 

NXSize size; 

The size of the image in screen pixels. 


METHOD TYPES 

Setting the size of the image - setSize: 

- getSize: 

Specifying information about the representation 

- setNumColors: 

- numColors 

- setAlpha: 

- hasAlpha 

- setBitsPerSample: 

- bitsPer Sample 

- setPixelsHigh: 

- pixelsHigh 

- setPixelsWide: 

- pixels Wide 
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Drawing the image - draw 

- draw At: 

- drawln: 

Archiving - read: 

- write: 


INSTANCE METHODS 

bitsPerSample 

- (int)bitsPerSample 

Returns the number of bits used to specify a single pixel in each component of the data. 
If the image isn’t specified by pixel values, but is device-independent, the return value 
will be NX_MATCHESDEVICE. 

See also: - setBitsPerSample: 
draw 

- (BOOL)draw 

Implemented by subclasses to draw the image at location (0.0, 0.0) in the current 
coordinate system. Subclass methods return YES if the image is successfully drawn, 
and NO if it isn’t. This version of the method simply returns YES. 

See also: - draw At:, - drawln: 
drawAt: 

- (BOOL)drawAt: (const NXPoint *)point 

Translates the current coordinate system to the location specified by point and has the 
receiver’s draw method draw the image at that point. 

This method returns NO without translating or drawing if the size of the image has not 
been set. Otherwise, it passes through the return of the draw method, which indicates 
whether the image is successfully drawn. 

The coordinate system is not restored after it has been translated. 

See also: - draw, - drawln: 


2-412 Chapter 2: Class Specifications 



drawln: 


- (BOOL)drawInr(const NXRect *)rect 

Draws the image so that it fits inside the rectangle referred to by rect. The current 
coordinate system is first translated to the point specified in the rectangle and is then 
scaled so the image will fit within the rectangle. The receiver’s draw method is then 
invoked to draw the image. 

This method returns NO without translating, scaling, or drawing if the size of the image 
has not been set. Otherwise it passes through the return of the draw method, which 
indicates whether the image is successfully drawn. 

The previous coordinate system is not restored after it has been altered. 

See also: - draw, - dr aw At: 

getSize: 

- getSize :(NXSize *)theSize 

Copies the size of the image to the structure referred to by theSize, and returns self. The 
size is provided in units of the base coordinate system. 

See also: - setSize: 

hasAlpha 

- (BOOL)hasAlpha 

Returns YES if the receiver has been informed that the image has a coverage 
component (alpha), and NO if not. 

See also: - setAlpha: 

numColors 

- (int)numColors 

Returns the number of color components in the image. For example, the return value 
will be 4 for images specified by cyan, magenta, yellow, and black (CMYK) or any 
other four components. It will be 3 for images specified by red, green, and blue (RGB), 
hue, saturation, and brightness (HSB), or any other three components. And it will be 1 
for images that use only a gray scale. NX_MATCHESDEVICE is a meaningful return 
value for representations that vary their drawing depending on the output device. 

See also: - setNumColors: 
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pixelsHigh 

- (int)pixelsHigh 

Returns the height of the image in pixels, as specified in the image data. If the image 
isn’t specified by pixel values, but is device-independent, the return value will be 
NX_MATCHESDEVICE. 

See also: - setPixelsHigh: 

pixelsWide 

- (int)pixelsWide 

Returns the width of the image in pixels, as specified in the image data. If the image 
isn’t specified by pixel values, but is device-independent, the return value will be 
NX_MATCHESDEVICE. 

See also: - setPixelsWide: 

read: 

- read:(NXTypedStream *)stream 

Reads the NXImageRep from the typed stream stream. 

See also: - write: 

setAlpha: 

- setAIpha:(BOOL)//<3g 

Informs the NXImageRep whether the image has an alpha component, flag should be 
YES if it does, and NO if it doesn’t. Returns self. 

See also: - hasAlpha 


setBitsPerSample: 

- setBitsPerSample:(int)a«/«f 

Informs the NXImageRep that the image has anlnt bits of data for each pixel in each 
component. If the image isn’t specified by pixel values, but is device-independent, 
anlnt should be NX_MATCHESDEVICE. Returns self. 

See also: - bitsPerSample 
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setNumColors: 

- setNumColors: (mi)anlnt 

Informs the NXImageRep that the image has anlnt number of color components. For 
color images with cyan, magenta, yellow, and black (CMYK) components, anlnt 
should be 4, for color images with red, green, and blue (RGB) components, it should 
be 3, and for images that use only a gray scale, it should be 1. The alpha component is 
not included. NX_MATCHESDEVICE could be a meaningful value, if the 
representation varies its drawing depending on the output device. Returns self. 

See also: - numColors 

setPixelsHigh: 

- setPixelsHigh: (int)anlnt 

Informs the NXImageRep that the data specifies an image anlnt pixels high. If the 
image isn’t specified by pixel values, but is device-independent, anlnt should be 
NX_MATCHESDEVICE. Returns self. 

See also: - pixelsHigh 

setPixelsWide: 

- setPixelsWide :(int )anlnt 

Informs the NXImageRep that the data specifies an image anlnt pixels wide. If the 
image isn’t specified by pixel values, but is device-independent, anlnt should be 
NX_MATCHESDEVICE. Returns self. 

See also: - pixels Wide 
setSize: 

- setSize: (const NXSize *)aSize 

Sets the size of the image in units of the base coordinate system, and returns self. This 
determines the size of the image when it’s rendered; it’s not necessarily the same as the 
width and height of the image in pixels as specified in the image data. 

See also: - getSize: 


write: 

- write: (NXTypedStream *)stream 

Writes the NXImageRep to the typed stream stream. 

See also: - read: 
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CONSTANTS AND DEFINED TYPES 

/* 

* NX_MATCHESDEVICE indicates a value that's variable, depending 

* on the output device. It can be passed to the setNumColors:, 

* setBitsPerSample:, setPixelsWide: , and setPixelsHigh: methods, 

* and is returned by their counterparts. 

*/ 

fdefine NXJVLATCHESDEVICE (0) 

/* 

* Names of segments 
*/ 

#define NX_EPSSEGMENT "_EPS" 

#define NXJTIFFSEGMENT "_TIFF" 

#define NX ICONSEGMENT " ICON" 
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NXJournaler 


INHERITS FROM Object 

DECLARED IN appkit/NXJoumaler.h 

CLASS DESCRIPTION 

The NXJournaler class defines an object that lets an application record and play back 
events and sounds, a process called journaling. By using an NXJournaler object, an 
application can journal events flowing to one or more applications—including itself. 
Optionally, sound can be recorded synchronously with the events. Later, the recorded 
events and sound can be played back, reenacting the activities as they occurred during 
the recording. With journaling, you can implement event-based macros or complete 
self-running demonstrations for your application. See the ShowAndTell application in 
/NextDeveloper/Demos for an example of journaling. 

Journaling is initiated by creating a new NXJournaler object and sending it a 
setEventStatus:soundStatus:eventStream:soundflle: message. The status 
arguments may have the values NX_STOPPED, NX_PLAYING, and 
NX_RECORDING. The event stream argument is a stream to record to or play back 
from. If you’re recording, any data in the stream will be overwritten. It’s not currently 
possible to add to the end of an existing event stream. The sound file argument is the 
name of a sound file to record to or play back from. 

When recording, by default all events going to any application are captured. 
Sometimes, you may not want certain applications to be recorded. For example, you 
might want to prevent the application that’s recording the journal from being recorded. 
There are two ways to control this: with the defaults system and by sending a 
setjournalable: message to the Application object. Of the two, the defaults system is 
the more general. 

To use the defaults system to control journaling, add this code to the initialize method 
of the object that will be controlling the journaling: 

+ initialize 
{ 

static NXDefaultsVector myDefaults = { 

{"NXAllowJournaling”, "NO"}, 

{NULL}}; 

NXRegisterDefaults{[NXApp appName], myDefaults); 
return self; 

} 

This will prevent the application that contains the object from being journaled unless a 
user overrides the default for that application in the user’s default database. 


Application Kit Classes: NXJournaler 2-417 



Users can also disallow journaling of any given application by adding an entry to their 
defaults database for that application. This would be done by entering the following 
command line in a Terminal window: 

dwrite applicationName NXAllowJournaling NO 


A less common way of allowing or disallowing journaling in an application is to send 
a setjournalable: message to the Application object. This allows more precise 
runtime control over journaling in that application. 

Event recording may be aborted by clicking the right mouse button while holding down 
the Alternate key. (Note: For this to work, you must have the right mouse button 
enabled in the Preferences application.) Event playback can be aborted by typing a 
character with any key on the keyboard. 


INSTANCE VARIABLES 

Inherited from Object Class isa; 

Declared in NXJournaler (none) 


METHOD TYPES 

Initializing and freeing an NXJournaler 

- init 

- free 

Controlling journaling - setEventStatus: 

soundStatus: 

eventStream: 

soundfile: 

- getEventStatus: 

soundStatus: 

eventStream: 

soundfile: 

- setRecordDevice: 

- recordDevice 

Identifying associated objects - speaker 

- listener 

- setDelegate: 

- delegate 
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INSTANCE METHODS 


delegate 

- delegate 

Returns the NXJoumaler’s delegate. 

See also: - setDelegate: 

free 

- free 

Frees the NXJoumaler. Send this message to an NXJoumaler after you’re completely 
done with it. 


getE ventStatus: sound S tatus: e ventStr earn: soundfile: 

- getEventStatus:(int *)eventStatusPtr 

soundStatus : (int *)soundSta tusPtr 
eventStream:(NXStream **) streamPtr 
soundfile: (char **)soundfilePtr 

Provides status information about the NXJoumaler. Values returned at eventStatusPtr 
and soundStatusPtr can be NXJPLAYING, NX_RECORDING, or NX_STOPPED. 
streamPtr is the address of a pointer to the event stream. soundfilePtr is the address of 
a pointer to the name of the sound file. Any of the arguments may be NULL if you 
don’t want that piece of information. Returns self. 

See also: - setEventStatus:soundStatus:eventStream:soundfile: 


init 


- init 


Initializes a newly allocated NXJoumaler object. The delegate of the new object is nil. 
This is the designated initializer for an NXJoumaler object. Returns self. 

listener 
- listener 

Returns the listener used by the NXJoumaler to communicate with other applications. 
See also: - speaker 
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recordDevice 

- (int)recordDevice 

Returns whether sound is recorded from the CODEC microphone or from the DSR The 
return value is either NX_CODEC or NX_DSP. 

See also: - setRecordDevice: 

setDelegate: 

- setDe\egate:anObject 

Sets the delegate used by the NXJoumaler. The delegate is sent the method 
journalerDidEnd: when either playing or recording the journal finishes. If the journal 
was aborted, the delegate will first receive the message journalerDidUserAbort:. 
Returns self. 

See also: - delegate 

setE ventStatus: soundStatus: eventStream: soundfile: 

- setEventStatus:(int)eve«rStata l s' 

soundStatus: (mt)soundStatus 
eventStream :(NXStream *)stream 
soundfile: (const char *)soundfile 

Controls the recording and playback of events and sounds. This is the main control 
point of the NXJoumaler. The arguments eventStatus and soundStatus may be 
independently set to NX_STOPPED, NX_PLAYING, NX_RECORDING. By setting 
eventStatus to NX_RECORDING and soundStatus to NX_STOPPED, it’s possible to 
record events without the sound. By setting eventStatus to NX_PLAYING and 
soundStatus to NX_RECORDING, it’s possible to dub new sound over an existing 
event track. 

The stream argument is the stream to record events to or playback events from. When 
recording, any preexisting data in the stream will be overwritten. It’s not currently 
possible to record onto the end of an existing event stream. 

The soundfile argument is the name of the file to record sound to or playback sound 
from. 

See also: - getEventStatus:soundStatus:eventStream:soundfile: 
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setRecordDevice: 


- setRecordDevice: (mt)device 

Sets whether sound is recorded from the CODEC microphone (the default device) or 
from the DSP. The constants NX_CODEC and NX_DSP can be used to specify the 
device. 

See also: - recordDevice 

speaker 

- speaker 

Returns the speaker used by the NXJoumaler to communicate with the other 
applications. 

See also: - listener 


METHODS IMPLEMENTED BY THE DELEGATE 


journalerDidEnd: 

- journalerDidEnd ijoumaler 

Responds to a message informing the delegate that recording or playback of the journal 
is finished or has been aborted. 

See also: - journalerDidUserAbort: 

journalerDidUser Abort: 

- journalerDidUser Abort :journaler 

Responds to a message informing the delegate that the user has aborted the recording 
or playback session. A journalerDidUser Abort: message is sent when the 
NXJoumaler in the controlling application receives notice from one of the controlled 
applications that the user has generated an abort event during recording or playback. 
The delegate receives this message just before the NXJoumaler stops the recording or 
playback. 

See also: -journalerDidEnd: 
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CONSTANTS AND DEFINED TYPES 


/* NX_JOURNALEVENT subtypes */ 
fdefine NX_WINDRAGGED 0 

#define NX_MOUSELOCATION 1 
#define NX LASTJRNEVENT 2 


/* Window encodings in .evt file */ 

#define NX_KEYWINDOW (-1) 

#define NX_MAINWINDOW (-2) 

#define NX_MAINMENU (-3) 

fdefine NX_MOUSEDOWNWINDOW (-4) 

#define NX_APPICONWINDOW (-5) 

#define NX_UNKNOWNWINDOW (-6) 

/* Values for eventStatus and soundStatus */ 

#define NX_STOPPED (0) 

fdefine NX_PLAYING (1) 

#define NX_RECORDING (2) 

/* Values for recordDevice */ 
fdefine NX__CODEC 0 

fdefine NX_DSP 1 

fdefine NX_JOURNALREQUEST "NXJournalerRequest" 


typedef struct { 
int 

unsigned int 
unsigned int 
unsigned int 
unsigned int 
}NXJournalHeader; 


version; 

offsetToAppNames; 
lastEventTime; 
reservedl; 
reserved2; 
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NXSplitView 


INHERITS FROM View : Responder : Object 

DECLARED IN appkit/NXSplitView.h 

CLASS DESCRIPTION 

The NXSplitView class defines an object that lets several Views share a region within 
a window. The NXSplitView resizes its subviews so that each subview is the same 
width as the NXSplitView, and the total of the subviews ’ heights is equal to the height 
of the NXSplitView. The NXSplitView positions its subviews so that the first subview 
is at the top of the NXSplitView, and each successive subview is positioned below. 
The user can set the height of two subviews by moving a horizontal bar called the 
divider, which makes one subview smaller and the other larger. 

To add a View to an NXSplitView, you use the addSubview: View method. When the 
NXSplitView is displayed (as a result of a sending a display message, or because it was 
resized), it checks to see if its subviews are properly tiled. If not, it attempts to invoke 
the splitViewrresizeSubviews: delegate method. If the delegate doesn’t respond to 
this message, the adjustSubviews method is invoked to yield the default tiling 
behavior. If you want to set the height of a single subview to a specific value, you can 
simply set the height of its frame rectangle to that value. Remember, however, that the 
sum of the heights of the subviews plus the sum of the heights of the dividers must 
equal the frame height of the NXSplitView; otherwise, the NXSplitView will retile 
(and possibly resize) all its subviews. You can get the height of a divider with the 
dividerHeight method. 

When a mouse event occurs in an NXSplitView, the NXSplitView determines if the 
event occurred in one of the dividers. If so, the NXSplitView determines the limits for 
the divider’s travel, allows the delegate to limit the travel, and tracks the mouse to allow 
the user to drag the divider within the previously set limits. If the divider gets 
repositioned, the NXSplitView resizes the two affected subviews, informs the delegate 
that subviews were resized, and displays the affected Views and divider. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 
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Declared in NXSplitView 


id 


delegate; 


delegate The object that receives notification messages 

from the NXSplitView. 

METHOD TYPES 

Initializing a new NXSplitView - initFrame: 

Handling Events - mouseDown: 

- acceptsFirstMouse 

Managing component Views - adjusts ubviews 

- resizeSubviews: 

- dividerHeight 

- drawSelf:: 

- drawDivider: 

- setAutoresizeSubviews: 

Assigning a delegate - delegate 

- setDelegate: 


INSTANCE METHODS 

acceptsFirstMouse 

- (BOOL) acceptsFirstMouse 

Overrides the View method to allow the NXSplitView to respond to the mouse event 
that made its window the key window. Returns YES. 

See also: - acceptsFirstMouse (View) 

adjustSubviews 

- adjustSubviews 

Adjusts the heights of the NXSplitView’s subviews so that the total of the subviews’ 
heights fill the NXSplitView. The subviews are resized proportionally; the size of a 
subview relative to the other subviews doesn’t change. This method is invoked if the 
NXSplitView’s delegate doesn’t respond to a split ViewrresizeSubviews: message. 
Returns self. 

See also: - setDelegate:, - sp!itView:resizeSubviews: (delegate), 

- setFrame: (View) 
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delegate 

- delegate 

Returns the NXSplitView’s delegate. 

See also: - setDelegate: 

dividerHeight 

- (NXCoord)dividerHeight 

Returns the height of the divider. You can override this method to change the divider’s 
height, if necessary; the value that this method returns is used as the divider’s height. 

See also: - drawDivider: 

drawDivider: 

- drawDivider: (const NXRect *)aRect 

Draws a divider between two of the NXSplitView’s subviews. aRect describes the 
entire divider rectangle in the NXSplitView’s coordinates, which are flipped. The 
default implementation simply composites an image to the center of aRect, if you 
override this method and use a different icon to identify the divider, you may want to 
change the height of the divider. Returns self. 

See also: - dividerHeight, - drawSelf::, + findlmageNamed: (NXImage), 

- composite: to Point: (NXImage) 

drawSelf:: 

- drawSelf: (const NXRect *) rects :(int )rectCount 

Draws the NXSplitView. This method first checks all the NXSplitView’s subviews to 
ensure that they are positioned properly: Each subview should be the width of the 
NXSplitView and butted against the left edge of its frame rectangle. Each subview 
should also be butted against the divider for the previous subview. If the subviews 
aren’t positioned properly, this method invokes resizeSubviews: to reposition and 
resize the subviews. This method then fills the NXSplitView’s background area and 
invokes the drawDivider: method one or more times to draw all the required dividers. 
This method is invoked by the View methods for display; you shouldn’t invoke this 
method directly. Returns self. 

See also: - drawDivider:, - resizeSubviews:, - display: (View) 
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initFrame: 


- initFrame: (const NXRect *)frameRect 

Initializes the NXSplitView, which must be a newly allocated NXSplitView instance. 
The NXSplitView’s frame rectangle is made equivalent to that pointed to by frameRect. 
IfframeRect is NULL the default frame containing all zeros is unaltered. The 
NXSplitView’s coordinate system is flipped so that its origin is at its upper left comer, 
and a flag is set so the NXSplitView automatically resizes its subviews when it’s 
resized. This method is the designated initializer for the NXSplitView class. Returns 
self. 

See also: - setAutoresizeSubviews: (View) 

mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Overrides the Responder method so that the user can resize the NXSplitView’s 
subviews. If the mouse-down event occurs in one of the NXSplitView’s dividers, the 
NXSplitView determines the limits within which the divider can be dragged. It then 
gives the delegate the opportunity to modify the divider’s minimum and maximum 
limits. This method then tracks the mouse to allow the user to resize the subviews 
within the previously set limits. It then resizes the appropriate subviews, informs the 
delegate that the subviews were resized, and displays the appropriate area of the 
NXSplitView and its subviews. Returns self. 

See also: - splitView:getMinY:maxY:ofSubviewAt: (delegate), 

- splitViewDidResizeSubviews: (delegate), - setFrame: (View) 

resizeSubviews: 

- resizeSubviews: (const NXSize *)oldSize 

Ensures that the NXSplitView’s subviews are properly sized to fill the NXSplitView. If 
the delegate implements the splitView:resizeSubviews: method, that method is 
invoked to resize the subviews; otherwise, the adjustSubviews method is invoked to 
resize the subviews. In either case, this method then informs the delegate that the 
subviews were resized. oldSize is the previous bounds rectangle size. Returns self. 

See also: - splitView:resizeSubviews: (delegate), - adjustSubviews, 

- splitViewDidResizeSubviews: (delegate), - resizeSubviews: (View) 

setAutoresizeSubviews: 

- setAutoresizeSubviews: (BOOL )jlag 

Overrides View’s setAutoresizeSubviews: method to ensure that automatic resizing of 
subviews will not be disabled. You should never invoke this method. Returns self. 
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setDelegate: 

- seiDe\egate:anObject 

Makes anObject the NXSplitView’s delegate. The notification messages that the 
delegate can expect to receive are listed at the end of the NXSplitView class 
specifications. The delegate doesn’t need to implement all the delegate methods. 
Returns self. 

See also: - delegate 


METHODS IMPLEMENTED BY THE DELEGATE 


splitView:getMinY:maxY:ofSubviewAt: 

- splitViexvisender 

getMinY:(NXCoord *)minY 
maxY:(NXCoord *)maxY 
ofSubviewAt:(int )offset 

Allows the delegate to constrain the y coordinate limits of a divider when the user drags 
the mouse. This method is invoked before the NXSplitView begins tracking the mouse 
to position a divider. When this method is invoked, the limits have already been set and 
are stored in miriY (the topmost limit) and maxY (the bottommost limit). You may 
further constrain the limits by setting the variables indicated by miriY and maxY, but you 
cannot extend the divider limits. miriY and maxY are specified in the NXSplitView’s 
flipped coordinate system. The divider to be repositioned is indicated by offset; the 
divider between the first two subviews is indicated by an offset of zero. 

See also: - mouseDown: 

split V iew: resizeSub vie ws: 

- spMtView'.sender 

resizeSubviews: (const NXSize *)oldSize 

Allows the delegate to specify custom sizing behavior for the subviews of the 
NXSplitView. If the delegate implements this method, splitView:resizeSubviews: is 
invoked after the NXSplitView is resized; otherwise, adjustSubviews is invoked to 
retile the subviews. The old size of the NXSplitView is indicated by oldSize; the 
subviews should be resized to fill the NXSplitView’s new frame rectangle size. You 
may find it convenient to use NX_ADDRESS() to get the address of the array of the 
ids of the subviews in order to step through the subview list. 

See also: - adjustSubviews, - dividerHeight, - setFrame: (View), 
NX_ADDRESS() 
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splitViewDidResizeSub views: 

- split ViewDidResizeSub vie ws:sc/?<ficr 

Informs the delegate that the sizes of some or all of the NXSplitView’s subviews were 
changed. This method is invoked when the NXSplit View resizes all its subviews 
because its frame rectangle changed, and also after the NXSplit View resizes two 
subviews in response to the repositioning of a divider. 

See also: - resizeSubviews:, - mouseDown: 
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Object Methods 


INHERITS FROM none ( Object is the root class.) 

DECLARED IN appkit/Application.h 

CLASS DESCRIPTION 

The methods described here are declared in the Application Kit as additions to the 
Object class. However, the Object class itself is a “common class,” not part of the Kit. 
For a description of the class and the other methods it defines, see “Object” in the 
“Common Classes” section above. 


METHOD TYPES 

Sending messages determined at run time 

- perform:with:afterDelay:cancelPrevious: 


Saying whether to run the Print panel 

- shouldRunPrintPanel: 

Services menu support - readSelectionFromPasteboard: 

- writeSelectionToPasteboarditypes: 


INSTANCE METHODS 


perform:with:afterDelay:cancelPrevious: 

- perform :(SEL)aSelector 
with lanObject 
afterDelay : (int)ras 
cancelPrevious: (BOOL )flag 

Registers a timed entry to send an aSelector message to the receiver after a delay of at 
least ms milliseconds, and returns self. The aSelector method should not have a 
significant return value and should take a single argument of type id; anObject will be 
the argument passed in the message. Since timed entries are checked only when the 
application goes to get another event, program activity could delay the aSelector 
message well beyond ms milliseconds. 

If flag is YES and another perform:with:afterDelay:cancelPrevious: message is sent 
to the same receiver to have it perform the same aSelector method, the first request to 
perform the aSelector method is canceled. Thus successive 
perform:with:afterDelay:canceIPrevious: messages can repeatedly postpone the 
aSelector message. 
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If flag is NO, each perform:with:afterDelay:cancelPrevious: message will cause 
another delayed aSelector message to be sent. 

This method permits you to register an action in response to a user event (such as a 
click), but delay it in case subsequent events alter the environment in which the action 
would be performed (for example, if the click turns out to be double-click). It can also 
be used to delay a free message to an object until after the application has finished 
responding to the current event, or to postpone a message that updates a display until 
after a number of changes have accumulated. 

See also: - perform:with: (Object) 

readSelectionFromPasteboard: 

- readSelectionFromPasteboardiphoard 

Implemented by subclasses to replace the current selection with data read from the 
Pasteboard object pboard. The data would have been placed in the pasteboard by 
another application in response to a remote message from the Services menu. A 
readSelectionFromPasteboard: message is sent to the same object that previously 
received a writeSelectionToPasteboard:types: message. 

There’s no default readSelectionFromPasteboard: method. The Application Kit 
declares a prototype for this method in the Object class, but doesn’t implement it. 

See also: - writeSelectionToPasteboard:types: 

shouldRunPr intPanel: 

#import <appkit/View.h> 

- (BOOL)shouldRunPrintPanel :aView 

Implemented by subclasses to indicate whether the Print panel (or Fax panel) should be 
run before printing (or faxing) a View or a Window. 

Printing requests are initiated by sending a View or Window a message to perform one 
of these two methods: 

printPSCode: (View and Window) 
smartPrintPSCode: (Window only) 

Each method takes an id argument, which usually identifies the initiator of the print 
request (the object that sent the message). A shouldRunPrintPanel: message is sent 
back to that object, if the object can respond to the message. The aView argument 
identifies the View being printed. 

If shouldRunPrintPanel: returns YES, the Print panel is run before printing begins. 
If it returns NO, the panel is not run, and the previous settings of the Print panel are 
used. The Print panel is also run if this method is not implemented. 
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Requests to fax a View or a Window can be initiated (by users) from within the Print 
panel. An application can also bypass the Print panel using either of the following two 
methods, which parallel the printing methods listed above: 

faxPSCode: (View and Window) 
smartFaxPSCode: (Window only) 

Like the printing methods, these methods each take an id argument, and the argument 
is sent a shouldRunPrintPanel: message if it can respond. However, in this case, the 
value returned by shouldRunPrintPanel: indicates whether the Fax panel (not the 
Print panel) should be run. 

There’s no default implementation of the shouldRunPrintPanel: method. The 
Application Kit declares a prototype for this method in the Object class, but doesn’t 
define it. 

See also: - printPSCode: (View and Window), - smartPrintPSCode: (Window), 

- faxPSCode: (View and Window), - smartFaxPSCode: (Window) 


writeSelectionToPasteboard:types: 

- (BOOL)writeSelectionToPasteboard:pboard types:(NXAtom *)types 

Implemented by subclasses to write the current selection to the Pasteboard object 
pboard. The selection should be written as one or more of the data types listed in types. 
After writing the data, this method should return YES. If for any reason it can’t write 
the data, it should return NO. 

A writeSelectionToPasteboard:types: message is sent to the first responder when the 
user chooses a command from the Services menu, but only if the receiver didn’t return 
nil to a previous validRequestorForSendType:andReturnType: message. After the 
data is written to the pasteboard, a remote message is sent to the application that 
provides the service the user requested. If the service provider supplies return data to 
replace the selection, the first responder will receive a subsequent 
readSelectionFromPasteboard : message. 

There’s no default writeSelectionToPasteboard:types: method. The Application Kit 
declares a prototype for this method in the Object class, but doesn’t implement it. 

See also: - validRequestorForSendType:andReturnType: (Responder), 

- readSelectionFromPasteboard: 
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OpenPanel 


INHERITS FROM SavePanel: Panel: Window : Responder: Object 

DECLARED IN appkit/OpenPanel.h 

CLASS DESCRIPTION 

The OpenPanel provides a convenient way for an application to query the user for the 
name of a file to open. It can only be run modally (the user should use the directory 
browser in the Workspace for non-modal opens). It allows the specification of certain 
types (i.e., file name extensions) of files to be opened. 

Every application has one and only one OpenPanel, and the new method returns a 
pointer to it. Do not attempt to create a new OpenPanel using the methods alloc or 
allocFromZone; these methods are inherited from SavePanel, which overrides them to 
return errors if used. 

See the class description for SavePanel for more information. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from Window 

NXRect 

frame; 


id 

contentView; 


id 

delegate; 


id 

firstResponder; 


id 

lastLeftHit; 


id 

lastRightHit; 


id 

counterpart; 


id 

fieldEditor; 


int 

winEventMask; 


int 

windowNum; 


float 

backgroundGray; 


struct _wFlags 

wFlags; 


struct _wFlags2 

wFlags2; 

Inherited from Panel 

(none) 



Application Kit Classes: OpenPanel 2-433 



Inherited from SavePanel 


Declared in OpenPanel 


id 

id 

id 

id 

id 

char 

char 

const char 
char 

struct _spFlags 
unsigned short 

char 


form; 

browser; 

okButton; 

accessory View; 

separator; 

*filename; 

^directory; 

**filenames; 

*requiredType; 

spFlags; 

directorySize; 

**filterTypes; 


filterTypes 


File types allowed to open 


METHOD TYPES 


Creating and Freeing an OpenPanel + new 

+ newContent:style:backing:buttonMask:defer: 
- free 


Filtering files 
Querying the chosen files 
Running the OpenPanel 


- allowMultipleFiles: 

- filenames 

- runModalForDirectory:file: 

- runModalForDirectory:file:types: 

- runModalForTypes: 


CLASS METHODS 


new 
+ new 

Creates, if necessary, and returns the shared instance of OpenPanel. Each application 
has just one instance of OpenPanel. This method is implemented to override the 
inherited new method to assure that only one instance of OpenPanel is created in an 
application. 
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newContent:style:backing:buttonMask:defer: 

+ newContent: (const NXRect *)contentRect 
style :(int)aStyle 
backing: (int )bujferingType 
buttonMask : (int )mask 
defer : (B OOL )flag 

Don’t use this method, invoke new instead. This method is implemented to override 
the newContent:style:backing:buttonMask:defer: method inherited from 
SavePanel. Returns self. 

See also: + new 


INSTANCE METHODS 


allowMultipleFiles: 

- allowMultipleFiles:(BOOL)/?<2g 

If flag is YES, then the user can select more than one file in the browser. If multiple 
files are allowed, then the filenames method will be non-NULL only if one and only 
one file was selected. The filenames method will always return the selected files (even 
if only one file was selected). Note further that, though filenames always returns a 
fully-specified path, filenames never returns a fully-specified path (the files in the list 
are always relative to the path returned by directory). Returns self. 

See also: - filenames 

filenames 

- (const char *const *)filenames 

Returns a NULL terminated list of files (relative to the path returned by directory). 
This will be valid even if allowMultipleFiles is NO. This is the preferred way to get 
the name or names of any files that the user has chosen. 

free 

- free 

Frees the storage used by the shared OpenPanel object and returns nil. The next time 
new is sent to the OpenPanel, it will be recreated. You probably never need to invoke 
this method since there is one shared instance of the OpenPanel. 

See also: + new 
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runModalForDirectoryifile: 

- (int)runModalForDirectory:(const char *)path file:(const char *) filename 

Initializes the panel to the file specified by path and filename , then displays it and 
begins its event loop. Returns self. 

runModalForDirectoryifileitypes: 

- (int)runModalForDirectory:(const char *)path 

file:(const char *) filename 
types:(const char *const *)fileTypes 

Loads up the directory specified in path and optionally sets filename as the default file 
to open. fileTypes is a NULL-terminated list of suffixes (not including the “”’s) to be 
used to filter which files the user is given the opportunity to open. If the FIRST item in 
the list is a NULL, then all ASCII files will be included. Returns self. 

runModalForTypes: 

- (int)runModalForTypes: (const char * const *)fileTypes 

Same as runModalForDirectoryifile:types: except that the last directory from which 
a file was chosen is used. Returns self. 


CONSTANTS AND DEFINED TYPES 

/* Tags for the Views in a SavePanel */ 

#define NX_OPICONBUTTON NX_SPICONBUTTON 

tdefine NX_OPTITLEFIELD NX_SPTITLEFIELD 

#define NX_OPCANCELBUTTON NX_SPCANCELBUTTON 

#define NX_OPOKBUTTON NX_SPOKBUTTON 

#define NX OPFORM NX SPFORM 
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PageLayout 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN appkit/PageLayout.h 

CLASS DESCRIPTION 

PageLayout is a type of Panel that queries the user for information such as paper type 
and orientation. This information is passed to the Application object’s Printlnfo object, 
and is later used when printing. You can invoke the set Accessory View: method to add 
your own View to the PageLayout panel to extend its functionality. An application can 
have only one PageLayout object; the new method returns the previous instance of the 
PageLayout object if one already exists. Most applications will bring up this panel by 
invoking the Application method runPageLayout: (this method is sent up the 
responder chain when you click the Page Layout menu item), but you can also run the 
panel with the PageLayout method runModal. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from Window 

NXRect 

frame; 


id 

contentView; 


id 

delegate; 


id 

firstResponder; 


id 

lastLeftHit; 


id 

lastRightHit; 


id 

counterpart; 


id 

fieldEditor; 


int 

winEventMask; 


int 

windowNum; 


float 

backgroundGray; 


struct _wFlags 

wFlags; 


struct _wFlags2 

wFlags2; 

Inherited from Panel 

(none) 
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Declared in PageLayout 


applcon 

height 

width 

ok 

cancel 

orientation 

scale 

paperSizeList 

layoutList 

unitsList 

exitTag 
paper View 

accessory View 


id 

applcon; 

id 

height; 

id 

width; 

id 

ok; 

id 

cancel; 

id 

orientation; 

id 

scale; 

id 

paperSizeList; 

id 

layoutList; 

id 

unitsList; 

int 

exitTag; 

id 

paper View; 

id 

accessory View; 


The Button object with the Application’s icon. 

The Form object for paper height. 

The Form object for paper width. 

The OK Button object. 

The Cancel Button object. 

The Matrix object for choosing between portrait 
and landscape orientation. 

The TextField for the scaling factor. 

The Button object for the PopUpList of paper 
choices. 

The Button object for the PopUpList of layout 
choices. 

The Button object for the PopUpList of unit 
choices. 

The tag of the Button object the user clicked to 
exit the Panel. 

The View used to display the size and orientation 
of the selected paper type. A subclass could set 
this instance to its own View to display a 
customized paper representation. 

The optional View added by the application. 
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METHOD TYPES 


Creating and freeing an instance 


+ new 

+ newContent:style:backing:buttonMask:defer: 
- free 


Running the PageLayout panel - runModal 

Customizing the PageLayout panel - setAccessoryView: 

- accessory View 


Updating the panel’s display 


- pickedLayout: 

- pickedOrientation: 

- pickedPaperSize: 

- pickedUnits: 

- textDidEndrendChar: 

- textWillChange: 

- convertOldFactormewFactor: 

- pickedButton: 


Communicating with the Printlnfo object 

- readPrintlnfo 

- writePrintlnfo 


CLASS METHODS 

alloc 

Generates an error message. This method cannot be used to create PageLayout 
instances. Use new instead. 

See also: + new 

allocFromZone: 

Generates an error message. This method cannot be used to create PageLayout 
instances. Use new instead. 

See also: + new 

new 
+ new 

Creates and returns the Page Layout panel. This will return the existing instance of the 
Page Layout panel if one has already been created. 
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newContent: style rbacking: buttonM ask: defer: 

+ newContent:(const NXRect *)contentRect 
style :(int )aStyle 
b&cking:(int)bufferingType 
buttonMask : (int )mask 
defer: (B OOL)flag 

Used in the instantiation of the Page Layout panel. You shouldn’t use this method to 

create the panel; use new instead. 

See also: + new 


INSTANCE METHODS 


accessoryView 

- accessoryView 

Returns the custom accessory View set by set Accessory View:. 

See also: - setAccessoryView: 

con vertOldFactor: newFactor: 

- convertOldFactor: (float *)old newFactor: (float *)new 

Returns conversion factors for values displayed in the panel. If this method is invoked 
from within an override of the pickedUnits: method, it will set old to the conversion 
factor between the unit of points and the previous units selected; new will be set to the 
conversion factor between points and the new units just selected. If this method is 
invoked at other times, such as when the page layout information is being loaded with 
the readPrintlnfo method, both old and new will be set to the conversion factor 
between points and the currently selected units. See pickedUnits: for an example. 
Returns self. 

See also: - pickedUnits: 

free 

- free 

Frees all the memory used by the Page Layout panel. 

See also: + new 
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pickedButton: 

-pickedButton :sender 

Ends the current run of the Page Layout panel if all the entries in the panel are valid. If 
the entries are not valid, this method does nothing. This method is the target of the OK 
and Cancel buttons. If all the panel entries are valid, this method sets the exitTag 
instance variable to the tag of the button that the user clicked to dismiss the panel, and 
sends a stopModal message to the Application object. Returns self. 

See also: - runModal, - stopModal (Application) 

pickedLayout: 

- pickedLayoutisemfer 

Performed when the user selects an item from the layout list. You might override this 
method to update other controls you add to the panel. You can get the new layout with 
the message [[sender selectedCell] title]. Returns self. 

See also: - setAccessoryView:, - selectedltem (PopUpList), - selectedCell (Matrix) 

pickedOrientation: 

- pickedOrientation :sender 

Performed when the user selects a page orientation. This method updates the paper 
width and height forms. You can override it to update other controls you add to the 
panel. You can get the new orientation with the message [sender selectedCol], where 
a return value of 0 means portrait, and a value of 1 means landscape. Returns self. 

See also: - setAccessoryView:, - selectedCol (Matrix) 


pickedPaperSize: 

- pickedPaperSiz ^'.sender 

Performed when the user selects a paper size. This method updates the paper width and 
height forms, and may switch the page orientation. You can override this method to 
update other controls you add to the panel. You can get the new name of the new paper 
size with the message [[sender selectedCell] title]. Returns self. 

See also: - setAccessoryView:, - selectedltem (PopUpList), - selectedCell (Matrix) 
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pickedUnits: 

- pickedUnits ‘.sender 

Performed when the user selects a new unit of measurement. You can override this 
method to update other controls you add to the panel. You should do this for any fields 
you add that express dimensions on the page. To determine how to update your field, 
call the PageLayout method convertOIdFactorrnewFactor:. The first value will 
convert from the unit of points to the previous unit of measurement. The second will 
convert from points to the new unit of measurement. The following example supposes 
that a subclass of PageLayout adds a TextField stored in the instance variable myField: 

- pickedUnits:sender 

{ ' 

float old, new; 

/* At this point, the units have been selected, */ 

/* but not set. Get the conversion factors: */ 

[self convertOldFactor:Sold newFactor:&new]; 

/* Set my field based on the conversion factors */ 

[myField setFloatValue:([myField floatValue] * new / old)]; 

/* Now let the method set the selected units */ 
return [super pickedUnits:sender]; 

} 

See also: - convertOIdFactorrnewFactor:, - setAccessoryView: 

readPrintlnfo 

- readPrintlnfo 

Reads the Application’s global Printlnfo object, and sets the values of the Page Layout 
panel to those in the Printlnfo. This method is invoked from the runModal method; 
you should not need to invoke it yourself. Returns self. 

See also: - writePrintlnfo, - runModal 
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runModal 


- (int)runModal 

Runs the Page Layout panel. For most applications, this is the only method needed to 
use this object. It loads the current printing information into the panel from the 
Application’s global Printlnfo object. It then runs the panel using Application’s 
runModalFor: method. When the user finishes with the panel, it is hidden. If the user 
exited the panel via the OK button, the information that he filled in is written back to 
the global Printlnfo object. The method returns the tag of the button that the user chose 
to dismiss the panel (either NX_OKTAG or NX_CANCELTAG). Note that since 
runModalFor: is used to run the Page Layout panel, the pickedButton: method must 
terminate the modal run by invoking Application’s stopModal method. 

See also: - runPageLayout (Application), - pickedButton:, 

- stopModal (Application), - runModalFor: (Application) 

setAccessoryView: 

- set Accessory View:a View 

Adds aView to the contents of the Page Layout panel. Applications can invoke this 
method to add controls to extend the functionality of the panel. aView should be the 
top View in a View hierarchy. The Page Layout panel is automatically resized to 
accommodate aView. This method can be invoked repeatedly to change the accessory 
View depending on the situation. If aView is nil, then any accessory View that’s in the 
panel is removed. Returns the old accessory View. 

See also: - accessoryView 


textDidEndiendChar: 

- textDidEnditextObject endChar:(unsigned shor t)theChar 

Performed when user finishes typing a page size. Selects the correct orientation to 
match the new paper size. You can override this method to update other controls you 
add to the panel. The width and height fields are Form objects, so you can use the Form 
method floatValueAt:0 to get the values of these fields. Returns self. 

See also: - setAccessoryView:, - floatValueAt: (Form) 
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textWillChange: 

- (BOOL)textWillChange:tex?0h/ecr 

Performed when the user types in a page size. This method highlights the “Other” 
choice in the list of paper types. You can override this method to update other controls 
you add to the panel. This message is sent to the PageLayout object because it is the 
Text object’s delegate; it returns 0 to indicate that the text field can be changed. 

See also: - set Accessory View:, - textWillChange: (Text delegate) 

writePrintlnfo 

- writePrintlnfo 

Writes the settings of the Page Layout panel to the Application object’s global Printlnfo 
object. This method is invoked when the user quits the Page Layout panel by clicking 
the OK button. Returns self. 

See also: - readPrintlnfo, - runModal 


CONSTANTS AND DEFINED TYPES 

/* Tags of Controls in the Page Layout panel */ 

#define NX_PLICONBUTTON 50 

#define NX_PLTITLEFIELD 51 

#define NX_PLPAPERSIZEBUTTON 52 

#define NX_PLLAYOUTBUTTON 53 

#define NX_PLUNITSBUTTON 54 

#define NX_PLWIDTHFORM 55 

#define NX_PLHEIGHTFORM 56 

#define NX_PLPORTLANDMATRIX 57 

#define NX_PLSCALEFIELD 58 

#define NX_PLCANCELBUTTON NX_CANCELTAG 

#define NX PLOKBUTTON NX OKTAG 
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INHERITS FROM 


Window : Responder : Object 


DECLARED IN appkit/Panel.h 

CLASS DESCRIPTION 

A Panel is a Window that serves an auxiliary function within an application; it contains 

Views that give information to users and let users give instructions to the application. 

Usually, the Views are Control objects of some sort—Buttons, Forms, NXBrowsers, 

TextViewers, Sliders, and so on. Menu is a Panel subclass. 

Panels behave differently than other Windows in only a small number of ways, but the 

ways are important to the user interface: 

• Panels pass Command key-down events to the objects in their view hierarchies. 
This permits them to have keyboard alternatives. 

• Panels aren’t destroyed when closed; they’re simply moved off-screen (taken out 
of the screen list). 

• On-screen Panels are removed from the screen list when the user begins to work in 
another application, and are restored to the screen when the user returns to the 
Panel’s application. 

• Panels have a light gray, rather than white, background in their content area. 

To facilitate their intended roles in the user interface, some panels can be assigned 

special behaviors: 

• A panel can be precluded from becoming the key window until the user makes a 
selection (makes a View the first responder) indicating an intention to begin typing. 
This prevents key window status from shifting to the Panel unnecessarily. 

• Palettes and similar panels can be made to float above standard windows and other 
panels. This prevents them from being covered and keeps them readily available 
to the user. 

• A Panel can be made to work—to receive mouse and keyboard events—even when 
there’s an attention panel on-screen. This permits actions within the Panel to affect 
the attention panel. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from Window 

NXRect 

frame; 


id 

contentView; 


id 

delegate; 


id 

firstResponder; 


id 

lastLeftHit; 


id 

lastRightHit; 


id 

counterpart; 


id 

fieldEditor; 


int 

winEventMask; 


int 

windowNum; 


float 

backgroundGray; 


struct _wFlags 

wFlags; 


struct _wFlags2 

wFlags2; 

Declared in Panel 

(none) 



METHOD TYPES 

Initializing a new Panel - init 

- initContent:style:backing:buttonMask:defer: 

Handling events - commandKey: 

- keyDown: 

Determining the Panel interface - setBecomeKeyOnlylfNeeded: 

- doesBecomeKeyOnlylfNeeded 

- setFloatingPanel: 

- isFloatingPanel 

- setWorksWhenModal: 

- works WhenModal 
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INSTANCE METHODS 


commandKey: 

- (BOOL)commandKey:(NXEvent *)theEvent 

Intercepts commandKey: messages being passed from Window to Window, and 
translates them to performKeyEquivalent: messages for the Views within the Panel. 
This method returns YES if any of the Views can handle the event as its keyboard 
alternative, and NO if none of them can. A NO return continues the commandKey: 
message down the Application object’s list of windows; a YES return terminates it. 

The Application object initiates commandKey: messages when it gets key-down 
events with the Command key pressed. The Panel also initiates them, but just to itself, 
when it gets a keyDown: event message. The argument, theEvent, is a pointer to the 
key-down event. 

Before any performKeyEquivalent: messages are sent, a Panel that’s not on-screen 
receives an update message. This gives it a chance to make sure that its Views are 
properly enabled or disabled to reflect the current state of the application. 

See also: - keyDown:, - performKeyEquivalent: (View) 

doesBecomeKeyOnlylfNeeded 

- (BOOL)doesBecomeKeyOnlylfNeeded 

Returns whether the Panel refrains from becoming the key window until the user clicks 
within (sends a mouse-down event to) a View that can become the first responder. The 
default is NO. 

See also: - setBecomeKeyOnlylfNeeded: 


init 


- init 


Initializes the receiver, a newly allocated Panel object, by sending it an 
initContent:style:backing:buttonMask:defer: message with default parameters, and 
returns self. 

The Panel will have a content rectangle of minimal size. The Window Server won’t 
create a window for the Panel until the Panel is ready to be displayed on-screen; the 
window will be a buffered window. The Panel will have a title bar and close button, but 
no resize bar. Like all Windows, it’s initially placed out of the screen list. Its title is 
not set. 

See also: - initContent:style:backing:buttonMask:defer: 


Application Kit Classes: Panel 2-447 



initContent:styIe:backing:buttonMask:defer: 

- initContent: (const NXRect *)contentRect 

style :(int )aStyle 
backing: ( mt)bujferingType 

bu ttonMask : (int )mask 
defer: (B OOL)flag 

Initializes the receiver, a newly allocated Panel instance, and returns self. 

This method is the designated initializer for this class. It’s identical to the Window 
method of the same name, except that it additionally initializes the receiver so that it 
will behave like a panel in the user interface: 

• The Panel’s background color is set to be light gray. 

• The Panel will hide when the application it belongs to is deactivated. 

• The Panel won’t be freed when the user closes it. 

The new Panel is initially out of the Window Server’s screen list. To make it visible, 
you must display it (into the buffer) and then move it on-screen. 

See also: - initContent:style:backing:buttonMask:defer: (Window) 

isFloatingPanel 

- (BOOL)isFloatingPanel 

Returns whether the Panel floats above standard windows and other panels. The default 
is NO. 

See also: - setFloatingPanel: 
keyDown: 

- keyDown :(NXEvent *)theEvent 

Translates the key-down event into a commandKey: message for the Panel, thus 
interpreting the event as a potential keyboard alternative. If the Panel has a button that 
displays the Return symbol and the key-down event is for the Return key, it will operate 
the button. 

A Panel can receive keyDown: event messages only when it’s the key window and none 
of its Views is the first responder. 

See also: - commandKey: 


2-448 Chapter 2: Class Specifications 



setBecomeKeyOnlylfNeeded: 

- setBecomeKeyOnlylfNeeded : (BOOL )flag 

Sets whether the Panel becomes the key window only when the user makes a selection 
(causing one of its Views to become the first responder). Since this requires the user 
to perform an extra action (clicking in the View) before being able to type within the 
window, it’s appropriate only for Panels that don’t normally require text entry. You 
should consider setting this attribute only if (1) most of the controls within the Panel 
are not text fields, and (2) the choices that can be made by entering text can also be 
made in another way (or are only incidental to the way the panel is normally used). The 
default flag is NO. Returns self. 

See also: - doesBecomeKeyOnlylfNeeded, - keyDown: 


setFloatingPanel: 

- setFloatingPanel: (BOOL)flag 

Sets whether the Panel should be assigned to a window tier above standard windows. 
The default is NO. It’s appropriate for a Panel to float above other windows only if: 

• It’s oriented to the mouse rather than the keyboard—that is, it doesn’t become the 
key window (or becomes the key window only if needed), 

• It needs to remain visible while the user works in the application’s standard 
windows—for example, if the user must frequently move the cursor back and forth 
between a standard window and the panel (such as a tool palette) or the panel gives 
information relevant to the user’s actions within a standard window, 

• It’s small enough not to obscure much of what’s behind it, and 

• It doesn’t remain on-screen when the application is deactivated. 

All four of these test must be met for flag to be set to YES. Returns self. 

See also: - isFloatingPanel 

setWorksWhenModal: 

- setWorksWhenModal: (B OOL )flag 

Sets whether the Panel remains enabled to receive events and possibly become the key 
window even when a modal panel (attention panel) is on-screen. This is appropriate 
only for a Panel that needs to operate on attention panels. The default is NO. Returns 
self. 

See also: - worksWhenModal 
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worksWhenModal 


- (BOOL)setWorksWhenModal 

Returns whether the Panel can receive keyboard and mouse events and possibly become 
the key window, even when a modal panel (attention panel) is on-screen. The default 
is NO. 

See also: - setWorksWhenModal: 


CONSTANTS AND DEFINED TYPES 


/* 

* Values returned by NXRunAlertPanel () (also returned by 

* runModalSession: when the modal session is run with a Panel 

* provided by NXGetAlertPanel()) 


*/ 

#define NX_ALERTDEFAULT 1 
tdefine NX_ALERTALTERNATE 0 
#define NX_ALERTOTHER -1 
#define NX ALERTERROR -2 


/* 

* Tags for common buttons in panels 
*/ 

#define NX_OKTAG 1 

#define NX CANCELTAG 0 
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Pasteboard 


INHERITS FROM Object 

DECLARED IN appkit/Pasteboard.h 

CLASS DESCRIPTION 

Pasteboard objects transfer data to and from the pasteboard server, pbs. The server is 
shared by all running applications. It contains data that the user has cut or copied and 
may paste, as well as other data that one application wants to transfer to another. 
Pasteboard objects are an application’s sole interface to the server and to all pasteboard 
operations. 

Named Pasteboards 

Data in the pasteboard server is associated with a name that indicates how it’s to be 
used. Each set of named data is, in effect, a separate pasteboard, distinct from the 
others. An application keeps a separate Pasteboard object for each named pasteboard 
that it uses. There are four standard pasteboards in common use: 

Font pasteboard The pasteboard that holds font and character information 

and supports the Copy Font and Paste Font commands. 

Ruler pasteboard The pasteboard that holds information about paragraph 

formats in support of the Copy Ruler and Paste Ruler 
commands. 

Find pasteboard The pasteboard that holds information about the current 

state of the active application’s Find panel. This 
information permits users to enter a search string into the 
Find panel, then switch to another application to conduct 
the search. 

Selection pasteboard The pasteboard that’s used for ordinary cut, copy, and 

paste operations. It holds the contents of the last selection 
that’s been cut or copied. 

Each standard pasteboard is identified by a unique name designated by a global variable 
of type NXAtom: 

NXFontPboard 

NXRulerPboard 

NXFindPboard 

NXSelectionPboard 
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You can also create private pasteboards by asking for a Pasteboard object with any other 
name. The name of a private pasteboard can be passed to other applications to allow 
them to share the data it holds. 

The Pasteboard class makes sure there’s just one object for each named pasteboard. If 
you ask for a new object when one has already been created for the pasteboard, the 
existing one will be returned to you. For this reason, only the new and newName: 
methods defined in this class should be used to create Pasteboard objects; Object’s alloc 
and allocFromZone: methods can’t be used. 


Data Types 

Data can be placed in the pasteboard server in more than one representation. For 
example, an image might be provided both in Tag Image File Format (TIFF) and as 
encapsulated PostScript code (EPS). Multiple representations give pasting applications 
the option of choosing which data type to use. In general, an application taking data 
from the pasteboard should choose the richest representation it can handle—rich text 
over plain ASCII, for example. An application putting data in the pasteboard should 
promise to supply it in as many data types as possible, so that as many applications as 
possible can make use of it. 

Data types are identified by character strings containing a full type name. The 
following global variables are string pointers for the standard NeXT pasteboard types. 
They’re of type NXAtom. 


Type 

NXAsciiPboardType 

NXPostScriptPboardType 

NXTIFFPboardType 

NXRTFPboardType 

NXSoundPboardType 

NXFilenamePboardType 

NXTabularTextPboardType 

NXFontPboardType 

NXRulerPboardType 


Description 

Plain ASCII text 

Encapsulated PostScript code (EPS) 
Tag Image File Format (TIFF) 

Rich Text Format (RTF) 

The Sound object’s pasteboard type 
ASCII text designating a file name 
Tab-separated fields of ASCII text 
Font and character information 
Paragraph formatting information 


Other data types can also be used. For example, your application may keep data in a 
private format that’s richer than any of types listed above. That format can also be used 
as a pasteboard type. 


Reading and Writing Data 

The pasteboard server supports a simple interface to reading and writing data, using a 
pointer to the data and the length of the data in bytes. Data is written to the pasteboard 
using writeType:data:length: and read using readType:data:length:. In each case 
only a pointer to the data is passed. The pointer and a single copy of the data can be 
shared among many applications. 
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It’s often convenient to prepare data for the pasteboard by opening a memory stream 
and writing the data to it using functions like NXWrite(), NXPrintf(), and NXPutc(). 
After the data has been written, a pointer to the data and the number of bytes can be 
extracted from the stream and sent to the pasteboard server. Using a stream means that 
the data will be page-aligned, so it will occupy the fewest number of pages possible. 

Similarly, you can create a memory stream for the data received from the pasteboard 
server and use functions like NXGetcO, NXRead(), and NXScanf() to parse it. 
Objects can be archived to and from the pasteboard server using typed streams. 


Errors 

Except where errors are specifically mentioned in the method descriptions, any 
communications error with the pasteboard server causes an NX_pasteboardComm 
exception to be raised. 

INSTANCE VARIABLES 

Inherited from Object Class isa; 

Declared in Pasteboard id owner; 

owner The object responsible for putting data in the 

pasteboard. 


METHOD TYPES 


Creating and freeing a Pasteboard object 

+ new 

+ newName: 

- free 

- freeGlobally 


Referring to a Pasteboard by name + newName: 

- name 


Writing data 


- declareTypes mum: owner: 

- writeType:data:length: 


Reading data 


- changeCount 

- types 

- readType:data:length: 
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CLASS METHODS 


alloc 

Generates an error message. This method cannot be used to create Pasteboard 
instances. Use new or newName: instead. 

See also: + new, + newName: 
allocFromZone: 

Generates an error message. This method cannot be used to create Pasteboard 
instances. Use new or newName: instead. 

See also: + new, + newName: 

new 
+ new 

Returns the Pasteboard object for the selection pasteboard, by passing 
NXSelectionPboard to the newName: method. 

newName: 

+ newName: (const char *)name 

Returns the Pasteboard object for the name pasteboard. A new object is created only if 
the application doesn’t yet have a Pasteboard object for the specified name; otherwise, 
the existing one is returned. To get a standard pasteboard, name should be one of the 
following variables: 

NXFontPboard 

NXRulerPboard 

NXFindPboard 

NXSelectionPboard 

Other names can be assigned to create private pasteboards for other purposes. 
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INSTANCE METHODS 


changeCount 

- (int)changeCount 

Returns the current change count of the pasteboard. The change count is a system-wide 
global that increments every time the contents of the pasteboard changes (a new owner 
is declared). It allows applications the optimization of knowing whether the current 
data in the pasteboard is the same as the data they last received. 

An independent change count is maintained for each named pasteboard. 

See also: - declareTypesrnum: owner: 

declareTypes:num:owner: 

- declareTypes: (const char * const *)newTypes 

num:(int )numTypes 
owner '.newOwner 

Prepares the pasteboard for a change in its contents by declaring the new types of data 
it will contain and a new owner. This is the first step in responding to a user’s copy or 
cut command and must precede the messages that actually write the data. A 
declareTypes:num:owner: message is tantamount to changing the contents of the 
pasteboard. It invalidates the current contents of the pasteboard and increments its 
change count. 

numTypes is the number of types the new contents of the pasteboard may assume, and 
newTypes is an array of null-terminated strings that name those types. The types should 
be ordered according to the preference of the source application, with the most 
preferred type coming first. Usually, the richest representation is the one most 
preferred. 

The newOwner is the object responsible for writing data to the pasteboard in all the 
types listed in newTypes. Data is written using the writeType:data:length: method. 
You can write the data immediately after declaring the types, or wait until it’s required 
for a paste operation. If you wait, the owner will receive a pasteboard:provideData: 
message requesting the data in a particular type when it’s needed. You might choose 
to write data immediately for the most preferred type, but wait for the others to see 
whether they’ll be requested. 

The newOwner can be NULL if data is provided for all types immediately. Otherwise, 
the owner should be an object that won’t be freed. It should not, for example, be the 
View that displays the data if that View is in a window that might be closed. 

Returns self. 

See also: - writeiype: data .’length:, - pasteboard:provideData: 
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free 


- free 

Frees the Pasteboard object. A Pasteboard object should not be freed if there’s a chance 
that the application might want to use the named pasteboard again; standard 
pasteboards generally should not be freed at all. 

freeGlobally 

- freeGlobally 

Frees the Pasteboard object and the domain for its name within the pasteboard server. 
This means that no other application will be able to use the named pasteboard. A 
temporary, privately named pasteboard can be freed when it’s no longer needed, but a 
standard pasteboard should never be freed globally. 

name 

- (const char *)name 

Returns the name of the Pasteboard object. 

See also: + newName: 

readType: data .'length: 

- readType: (const char *)dataType 

data: (char **)theData 
length:(int *)numBytes 

Reads the dataType representation of the current contents of the pasteboard. dataType 
should be one of the types returned by the types method. The data is read by setting 
the pointer referred to by theData to the address of the data, and setting the integer 
referred to by numBytes to the length of the data in bytes. 

If the data is successfully read, this method returns self. It returns nil if the contents of 
the pasteboard have changed (if the change count has been incremented by a 
dec!areTypes:num:owner message) since they were last checked with the types 
method. It also returns nil if the pasteboard server can’t supply the data in time—for 
example, if the pasteboard’s owner is slow in responding to a 
pasteboard:provideData: message and the interprocess communication times out. 
All other errors raise an NX_pasteboardComm exception. 

If nil is returned, the application should put up a panel informing the user that it was 
unable to carry out the paste operation. It should not attempt to use the pointer referred 
to by theData, as it won’t be valid. 
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The memory for the data that this method provides is allocated directly from the Mach 
virtual memory manager, not through malloc(); it therefore should be freed only by 
vmdeallocateQ, not free(). For example: 


char *data; 
int length; 

if ([myPasteboard readType:NXAsciiPboardType 

data:&data length:Slength]) 

{ 

/* Use the data here, keeping it for as long as necessary */ 
vm_deallocate(task_self(), data, length); 

} 

See also: - types 
types 

- (const NXAtom *)types 

Returns the list of the types that were declared for the current contents of the 
pasteboard. The list is an array of character pointers holding the type names, with the 
last pointer being NULL. Each of the pointers is of type NXAtom, meaning that the 
type name is a unique string. 

Types are listed in the same order that they were declared. A types message should be 
sent before reading any data from the pasteboard. 

See also: - declareTypes:num:owner:, - readType: datarlength:, 
NXUniqueStringO 

writeType:data:length: 

- writeType: (const char *)dataType 

data:(const char *)theData 
length: (intjwwmRytes 

Writes data to the pasteboard server. dataType gives the type of data being written; it 
must be a type that was declared in the previous declareTypes:mim:owner: message. 
theData points to the data to be sent to the pasteboard server, and numBytes is the length 
of the data in bytes. 

A separate writeType:data:length: message is required for each data representation 
that’s written to the server. 

This method returns self if the data is successfully written. It returns nil if an object in 
another application has become the owner of the pasteboard. Any other error raises an 
NX_pasteboardComm exception. 

See also: - declareTypes:num:owner: 
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METHODS IMPLEMENTED BY THE OWNER 


pasteboard:provideData: 

- pasteboard '.sender provideData:(NXAtom)fype 

Implemented by the owner (previously declared in a declareTypes:num:owner: 
message) to provide promised data. The owner receives a pasteboard:provideData: 
message from the sender Pasteboard when the data is required for a paste operation; 
type gives the type of data being requested. The requested data should be written to 
sender using the writeType:data:length: method. 

pasteboard:provideData: messages may also be sent to the owner when the 
application is shut down through Application’s terminate: method. This is the method 
that’s invoked in response to a Quit command. Thus the user can copy something to 
the pasteboard, quit the application, and still paste the data that was copied. 

A pasteboard:provideData: message is sent only if type data hasn’t already been 
supplied. Instead of writing all data types when the cut or copy operation is done, an 
application can choose to implement this method to provide the data for certain types 
only when they’re requested. 

If an application writes data to the pasteboard in the richest, and therefore most 
preferred, type at the time of a cut or copy operation, its pasteboard:provideData: 
method can simply read that data from the pasteboard, convert it to the requested type, 
and write it back to the pasteboard as the new type. 

See also: - declareiypes:num:owner:, - writeType:data:length: 


CONSTANTS AND DEFINED TYPES 


/* 

* standard Pasteboard types 


*/ 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

extern 

NXAtom 

/* 



NXAsciiPboardType; 

NXPostScriptPboardType; 
NXTIFFPboardType; 
NXRTFPboardType; 
NXFilenamePboardType; 
NXTabularTextPboardType; 
NXFontPboardType; 
NXRulerPboardType; 


* standard Pasteboard names 

*/ 

extern NXAtom NXSelectionPboard; 
extern NXAtom NXFontPboard; 
extern NXAtom NXRulerPboard; 
extern NXAtom NXFindPboard; 
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PopUpList 


INHERITS FROM Menu : Panel: Window : Responder : Object 

DECLARED IN appkit/PopUpList.h 


CLASS DESCRIPTION 

PopUpList is used to create a pop-up list of items. The list is popped up in response to 
the action message popUp:, usually sent from a Button that acts as a “cover” for the 
PopUpList. The sender of the popUp: message must respond to the messages title and 
setTitle:; it can be any subclass of View. If the sender is a Matrix, the selectedCell 
must respond to those messages. In the Interface Builder, a PopUpList and a Button to 
activate it are available as a single palette item. 

A PopUpList can actually be one of two types: pop-up or pull-down. In the Interface 
Builder, you can select the type by selecting the appropriate icon in the Inspector panel. 
A pop-up list’s button title changes as items are selected from the list; a pull-down list’s 
button title doesn’t change. 

Accessing the PopUpList’s Button is useful if you want to change the title displayed for 
the list. To access the Button from your code, give it a tag in the Interface Builder’s 
Inspector. Send a setTitle: message to the Button to change the title string it displays. 
If the title you send isn’t represented in the PopUpList, it’s added at the top of the list 
the next time the user manipulates the Button. 

PopUpList is not a control. When you invoke setAction: and setTarget:, you are 
setting the action and target of the matrix used to display the list elements. The matrix 
itself actually sends the action message to the target as items are chosen from the 
PopUpList. 


INSTANCE VARIABLES 



Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 
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Inherited from Window NXRect 

id 

id 

id 

id 

id 

id 

id 

int 

int 

float 

struct _wFlags 
struct _wFlags2 

Inherited from Panel (none) 

Inherited from Menu id 

id 

id 

NXPoint 

id 

struct _menuFlags 

Declared in PopUpList (none) 


METHOD TYPES 

Initializing a PopUpList - init 

Setting up the items - addltem: 

- count 

- indexOfltem: 

- insertltem:at: 

- removeltem: 

- removeltemAt: 

Interacting with the Button - changeButtonTitle: 

- getButtonFrame: 

Activating the PopUpList - popUp: 

Returning the user’s selection - selectedltem 

Modifying the items - font 

- setFont: 


frame; 

contentView; 

delegate; 

firstResponder; 

lastLeftHit; 

lastRightHit; 

counterpart; 

fieldEditor; 

winEventMask; 

windowNum; 

backgroundGray; 

wFlags; 

wFlags2; 


supermenu; 

matrix; 

attachedMenu; 

lastLocation; 

reserved; 

menuFlags; 
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Target and action 


- action 

- setAction: 

- setTarget: 

- target 

Resizing the PopUpList - size Window:: 


INSTANCE METHODS 

action 

- (SEL)action 

Returns the action which will be sent when an item is selected from the list. 

See also: - setAction: 

addltem: 

- addltem: (const char *)title 

Adds the item with the name title to the PopUpList. The newly added cell is returned. 
The new item is added to the end of the list. 

Note: Popping up a list from a sender whose title is not in the list will cause that title 
to be added to the list (at the beginning of the list). 

See also: - setTarget: 

changeButtonTitle: 

- changeButtonTitle: (BOOL)/7<2£ 

If flag is YES, then when a selection is made from the list, the title of the selection 
becomes the title of the Control (usually a Button) which sent the popUp: message. If 
NO, then no such change occurs. YES is the default. Returns self. 

count 

- (unsigned int)count 

Returns the number of entries in the list. 

font 

- font 

Returns the font that is used to draw the items in the PopUpList. 
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getButtonFrame: 

- getButtonFrame :(NXRect *)bframe 

Returns, by reference, the frame for the button which is used to pop this list up. 

indexOfltem: 

- (int)indexOfltem: (const char *)title 

Returns the index of the item title. If title is not in the list, returns -1. 


init 


- init 


Initializes and returns the receiver, a new instance of PopUpList. This method is the 
designated initializer for PopUpList. PopUpList does not override the designated 
initializers for Menu, Panel, or Window. Use only this method to initialize new 
instances of PopUpList. If you create a subclass of PopUpList that performs its own 
initialization, you must override this method. 

insertltem:at: 

- insertltem: (const char *)title at:(unsigned int )index 

Inserts an item at the specified point in the PopUpList. The index starts with item 0 at 
the top of the list. Returns the newly inserted Cell. 

popUp: 

- popUprsewcfer 

This is the action message sent by an object, usually a Button, whose target is the 
PopUpList. The sender must be either a subclass of View that responds to the messages 
title and setTitle: or a subclass of Matrix whose selectedCell responds to title and 
setTitle:. 

This method works if and only if the Application’s currentEvent is a mouse down; 
thus, it should be invoked only as a result of a mouse-down occurring somewhere. 
When a selection is made in the PopUpList, the Matrix that displays PopUpList’s 
entries sends the action to the target. Returns self. 

See also: - setAction:, - setTarget: 
removeltem: 

- removeltem: (const char *)title 

Removes the item with the name title from the list and returns the Cell used to draw the 
item. 
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removeltemAt: 

- removeltemAt: (unsigned 'mi)index 

Removes the item at the specified index. Returns the Cell used to draw the title at that 
location. 

selectedltem 

- (const char *)selectedltem 

Returns the title of the currently selected item. The target of the PopUpList can get the 
title of the selected item by sending either [[sender selectedCell] title] or 
[[sender window] selectedltem] messages. The former is preferred. 

setAction: 

- setAction:(SEL)< 2 SW£ctor 

Sets the action sent when an item is selected from the PopUpList. This method invokes 
the setAction: method of the Matrix containing the list of items. Returns self. 

See also: - setAction: (Matrix) 

setFont: 

- setFont ifontld 

Sets the font that is used to draw the PopUpList. Returns self. 

setTarget: 

- setTargetianObject 

Sets the object to which an action will be sent when an item is selected from the list. 
This method invokes the setTarget: method on the Matrix containing the list of items. 
Returns self. 

See also: - setTarget: (Matrix), - target 


sizeWindow:: 

- sizeWindow: (NXCoord )width : (NXCoord)height 

Never invoke this method directly. This method is overridden from Menu because 
PopUpList needs to surround itself with a dark gray border, and thus needs to be one 
pixel wider and taller than a Menu. Returns self. 
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target 
- target 

Returns the object to which the action will be sent when an item is selected from the 
list. The default value is nil, which causes the action message to be sent down the 
responder chain. 

See also: - setTarget: 
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Printlnfo 


INHERITS FROM Object 

DECLARED IN appkit/Printlnfo.h 

CLASS DESCRIPTION 

The Printlnfo class contains all information describing a given print job. This includes 
parameters set in the Page Layout panel, and the Print panel. The units of the paper 
rectangle and margins are points (72 points equals 1 inch). 

The paperType, paperRect, and orientation variables are interrelated. A given paper 
type has a size, which determines what that paper type’s default orientation is 
(landscape if the width is greater than the height, else portrait). If the user chooses the 
contrary orientation, the size components in paperRect are reversed. These 
relationships between paperType, paperRect, and orientation must be maintained. 

The methods for setting these variables have an andAdjust: keyword for a Boolean 
parameter that can be used to maintain the above relationships. If you pass YES for the 
parameter, the variables will stayed synchronized. The Page Layout panel performs 
this maintenance for user actions. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in Printlnfo 

char 

*paperType; 


NXRect 

paperRect; 


NXCoord 

leftPageMargin; 


NXCoord 

rightPageMargin; 


NXCoord 

topPageMargin; 


NXCoord 

bottomPageMargin; 


float 

scalingFactor; 


char 

struct _pInfoFlags { 

pageOrder; 


unsigned int 

orientation: 1; 


unsigned int 

horizCenteredrl; 


unsigned int 

vertCenteredrl; 


unsigned int 

manualFeedil; 


unsigned int 

allPages.T; 


unsigned int 

horizPagination: 2; 


unsigned int 

vertPagination:2; 


} 

plnfoFlags; 
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int firstPage; 

int lastPage; 

int currentPage; 

int copies; 

char *outputFile; 

DPSContext context; 

char *printerName; 

char *printerType; 

char *printerHost; 

int resolution; 

short pagesPerSheet; 

paperType 

Type of paper. 

paperRect 

Rect representing paper’s area; origin is always 
(0,0). 

leftPageMargin 

Left margin. 

rightPageMargin 

Right margin. 

topPageMargin 

Top margin. 

bottomPageMargin 

Bottom margin. 

scalingFactor 

Factor to scale image by. 

pageOrder 

Order of pages in document. 

plnfoFlags .orientation 

Landscape or portrait mode. 

plnfoFlags .horizCentered 

True if the image is centered horizontally on the 
page. 

plnfoFlags.vertCentered 

True if the image is centered vertically on the 
page. 

plnfoFlags. manualFeed 

True if the job requires manual paper feed. 

plnfoFlags.allPages 

True if all the pages are to be printed. 

plnfoFlags .horizPagination 

Horizontal pagination. 

plnfoFlags.vertPagination 

Vertical pagination. 

firstPage 

First page to print. 

lastPage 

Last page to print. 

currentPage 

Current page being printed. 
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copies 

Number of copies to print. 

outputFile 

File to spool to. 

context 

Spooling context. 

printerName 

Name of printer to use. 

printerType 

Type of that printer. 

printerHost 

Host machine for that printer. An empty string 
indicates the local machine. 

resolution 

Resolution at which to print. 

pagesPerSheet 

The number of pages per sheet of paper. 

METHOD TYPES 

Initializing a new Printlnfo instance 

- init 

Freeing a Printlnfo instance 

- free 

Defining the printing rectangle 

- setMarginLeft:right:top:bottom: 

- getMarginLeft:right:top:bottom: 

- setOrientation:andAdjust: 

- orientation 

- setPaperRecfi.andAdjust: 

- paperRect 

- setPaperType:andAdjust: 

- paperType 

Setting which pages to print 

- setFirstPage: 

- firstPage 

- setLastPage: 

- lastPage 

- setAllPages: 

- isAllPages 

- currentPage 

Pagination 

- setHorizPagination: 

- horizPagination 

- setVertPagination: 

- vertPagination 

- setScalingFactor: 

- scalingFactor 
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Positioning the image on the page - setHorizCentered: 


Print job attributes 


Specifying the printer 


Spooling 


Archiving 


- isHorizCentered 

- setVertCentered: 

- isVertCentered 

- setPagesPerSheet: 

- pagesPerSheet 

- setPageOrder: 

- pageOrder 

- setManualFeed: 

- isManualFeed 

- setCopies: 

- copies 

- setResolution: 

- resolution 

- setPrinterName: 

- printerName 

- setPrinterType: 

- printerType 

- setPrinterHost: 

- printerHost 

- setOutputFile: 

- outputFile 

- setContext: 

- context 

- read: 

- write: 


INSTANCE METHODS 

context 

- (DPSContext)context 

Returns the Display PostScript context used for printing. 

copies 

- (int)copies 

Returns the number of copies of the document that will be printed. 


2-468 Chapter 2: Class Specifications 



currentPage 

- (int)currentPage 

Returns page number of the page currently being printed. This method is valid only 
when printing (or faxing) a View. See setFirstPage: for the meaning of the number 
returned. 

See also: - setFirstPage:, - printPSCode: (View) 

firstPage 

- (int)firstPage 

Returns the first page that will be printed in this document, assuming 
pInfoFlags.allPages is NO. See setFirstPage: for the meaning of the number 
returned. 

See also: - setFirstPage: 

free 

- free 

Frees all storage used by the Printlnfo object. 

getMarginLeft:right:top:bottom: 

- getMarginLeft:(NXCoord *)leftMargin 

right :(NXCoord *)rightMargin 
top:(NXCoord *)topMargin 
bottom:(NXCoord *)bottomMargin 

Returns the margins. All margins are in points, in the default coordinate system of the 
page. 

horizPagination 

- (int)horizPagination 

Returns the way in which pagination is done horizontally across the page. 


init 


- init 


Initializes the Printlnfo object after memory for it has been allocated by Object’s alloc 
or allocFromZone: methods. Returns self. 
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isAHPages 

- (BOOL)isAllPages 

Returns whether all the pages of this document are to be printed. If NO, then the pages 
that are to be printed are given by firstPage and lastPage. 

isHorizCentered 

- (BOOL)isHorizCentered 

Returns whether the default implementation of placePrintRectioffset: in the View 
class centers the image horizontally on the page. 

isManualFeed 

- (BOOL)isManualFeed 

Returns whether the pages for this print job will need to be manually fed to the printer. 

isVertCentered 

- (BOOL)isVertCentered 

Returns whether the default implementation of placePrintRect:offset: in the View 
class centers the image vertically on the page. 

lastPage 

- (int)lastPage 

Returns the last page that will be printed in this document, assuming allPages is NO. 
See setFirstPage: for the meaning of the number returned. 

See also: - setFirstPage: 

orientation 

- (char)orientation 

Returns the orientation (either NX_PORTRAIT or NXJLANDSCAPE). 

outputFile 

- (const char *)outputFile 

Returns the name of the file to which the generated PostScript code is sent. If this field 
is NULL, output will go to a temporary file. 
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pageOrder 

- (char)pageOrder 

Returns pageOrder. 

pagesPerSheet 

- (short)pagesPerSheet 

Returns the number of pages of the document printed per sheet of paper. 

paperRect 

- (const NXRect *)paperRect 

Returns a pointer to paperRect, which is measures the size of the paper in points. 

paperType 

- (const char *)paperType 

Returns the paperType of this Printlnfo object. If paperType is an unknown type, then 
an empty string is returned. 

printerHost 

- (const char *)printerHost 

Returns the name of the machine where the printer that we will print on resides. 

printerName 

- (const char *)printerName 

Returns the name of the printer on which we will print. 

printerType 

- (const char *)printerType 

Returns the type of printer on which we will print. 

read: 

- read:(NXTypedStream *)stream 

Reads the Printlnfo from the typed stream stream. 
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resolution 


- (int)resolution 

Returns the resolution at which we will print. 

scalingFactor 

- (float)scalingFactor 

Returns scalingFactor. 

setAHPages: 

- setAHPages: (ROOL)jlag 

Sets whether all the pages of the document are to be printed (as opposed to a subset 
given by the firstPage and lastPage values). 

setContext: 

- setContext: (D¥SCon\.txt)aContext 

Sets the DPS context we print through. This is normally done by the printing 
machinery in View. 

setCopies: 

- setCopies: (int)anlnt 

Sets the number of copies of the document that will be printed. 

setFirstPage: 

- setFirstPage , .(ml)anlnt 

Sets the page number of the first page that will be printed. 

Page numbers used by the Printlnfo object should use the same numbering as the pages 
in the document. For example, if a 10-page document’s first page is numbered page 20, 
then the Printlnfo’s first page should be set to 20 and the last page set to 29. This is the 
same numbering that the user will use to enter specific page ranges in the Print Panel. 

setHorizCentered: 

- setHorizC entered :(BOOL)flag 

Sets whether the default implementation of placePrintRect:offset: in the View class 
centers the image horizontally on the page. 
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setHorizPagination: 

- setHorizPagination :(int)mode 

Sets the way in which pagination is done horizontally across the page. The value 
NX_AUTOPAGINATION means the default Application Kit algorithm will be applied 
to divide the View being printed into pages. The value NX_FITPAGINATION means 
that the View will be scaled if necessary so that it fits on a single page horizontally; Any 
scaling applied will also affect the vertical dimension, maintaining a square aspect 
ratio. The value NX_CLIPPAGINATION means that the View will be clipped 
horizontally so that there is only one column of pages produced. 

setLastPage: 

- setLastPage: (int)anlnt 

Sets the page number of the last page that will be printed. See setFirstPage: for the 
meaning of the number passed. 

See also: - setFirstPage: 

setManualFeed: 

- setManualFeed:(BOOL)^g 

Sets whether the pages for this job will need to be manually fed to the printer. 

setMarginLeft: right: top: bottom: 

- setMarginLeft: (NXCoord)leftMargin 

right: (NXCoord )rightMargin 
top : (NXCoord )topMargin 
bottom : (NXCoord )bottomMargin 

Sets the margins. All margins are in points, in the default coordinate system of the 
page. 

setOrientation:andAdjust: 

- setOrientation:(char)me>de and Adjust: (BOOL)/Z<2g 

Sets orientation, mode should be either NX_PORTRAIT or NXJLANDSCAPE. 

If flag is NO, then only orientation is changed. If flag is YES, then paperRect is also 
updated to reflect the new orientation. 
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setOutputFile: 

- setOutputFile: (const char *)aString 

Sets the name of the file to which the generated PostScript code is sent. If this field is 
NULL, output will go to a temporary file. 


setPageOrder: 

- setPageOrder :(char)mode 


Sets pageOrder. mode should be one of these constants: 

NXJDESCENDINGORDER 

NXJSPECIALORDER 

NX_ASCENDINGORDER 

NXJJNKNOWNORDER 


setPagesPerSheet: 

- setPagesPerSheet: (short)aShort 

Sets the number of pages of the document printed per sheet of paper. This number is 
rounded up to a power of two when used by the system. 

setPaperRect’.andAdjust: 

- setPaperRect:(const NXRect *)aRect andAdjust:(BOOL)/Zag 

Sets paperRect. The origin of the rectangle is always constrained to be (0,0). The 
origin of aRect is ignored. Even though only the size of paperRect carries the 
information, it is stored as a rectangle to facilitate calculations, such as intersecting 
other objects with this rectangle. Points are the unit of measure. 

If flag is NO, then only paperRect is changed. If flag is YES, then orientation and 
paperType are updated to reflect the new paperRect. 

setPaperType :and Adjust: 

- setPaperType: (const char *)type andAdjust:(BOOL)/7<2g 

Sets paperType to type. If type is NULL, paper Type is set to an empty string. 

If flag is NO, or if flag is YES but type is not a recognized paper type, then only 
paperType will be changed. If flag is YES and type is a known paper type, then 
paperRect and orientation are updated to reflect the new type. 
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setPrinterHost: 

- setPrinterHost: (const char *)aString 

Sets the name of the machine where the printer on which we will print resides. If 
aString is an empty string, the host name is set to that of the local machine. 

setPrinterName: 

- setPrinterName: (const char *)aString 

Sets the name of the printer on which we will print. 

setPrinterType: 

- setPrinterType: (const char *)aString 

Sets the type of printer on which we will print. 

setResolution: 

- setResolution :(int)anlnt 

Sets the resolution at which we will print. 

setScalingFactor: 

- setScalingFactor :(f[oa.t)aFloat 

Sets scalingFactor. 

setVertCentered: 

- setVertCentered:(B OOL)flag 

Sets whether the default implementation of placePrintRect:offset: in the View class 
centers the image vertically on the page. 

setVertPagination: 

- setVertPagination :(int)mode 

Sets the way in which pagination is done vertically across the page. The value 
NX_AUTOPAGINATION means the default Application Kit algorithm will be applied 
to divide the View being printed into pages. The value NX_FITPAGINATION means 
that the View will be scaled if necessary so that it fits on a single page vertically. Any 
scaling applied will also affect the horizontal dimension, maintaining a square aspect 
ratio. The value NX_CLIPPAGINATION means that the View will be clipped 
vertically so that only one row of pages is produced. 
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vertPagination 

- (int)vertPagination 

Returns the way in which pagination is done vertically across the page. 

write: 

- write:(NXTypedStream *)stream 

Writes the receiving Printlnfo to the typed stream stream. 


CONSTANTS AND DEFINED TYPES 


/* Possible values for the 

page 

order */ 

#define NX_DESCENDINGORDER 

(-1) 

/* 

descending order of pages */ 

#define NX_SPECIALORDER 

0 

/* 

special order; tells the spooler 
to not rearrange pages */ 

#define NX_ASCENDINGORDER 

1 

/* 

ascending order of pages */ 

#define NX_UNKNOWNORDER 

2 

/* 

no page order written out */ 

/* The orientation of the page 

*/ 


#define NX_LANDSCAPE 

1 

/* 

long side horizontal */ 

#define NXJPORTRAIT 

0 

/* 

long side vertical */ 

/* Pagination modes */ 




#define NX_AUTOPAGINATION 

0 

/* 

auto pagination */ 

#define NX__FITPAGINATION 

1 

/* 

force image to fit on one page */ 

#define NX_CLIPPAGINATION 

2 

/* 

let image be clipped by page */ 
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PrintPanel 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN appkit/PrintPaneLh 

CLASS DESCRIPTION 

PrintPanel is a type of Panel that queries the user for information about the print job, 
such as which pages and how many copies to print. The PrintPanel contains a Choose 
button the user can click to display the ChoosePrinter panel and thereby select a printer; 
see ChoosePrinter’s class description for more information. 

Printing is typically initiated by the user choosing “Print” in the main menu, which 
sends a message to a View (or sometimes a Window) to perform its printPSCode: 
method. This method brings up the PrintPanel during the printing process by 
generating the shouldRunPrintPanel: method, which returns YES by default. The 
PrintPanel is displayed and run using its runModal method. This method loads 
information from the global Printlnfo object, runs the panel using runModalFor:, and 
returns the tag of the button the user clicked to dismiss the panel. See Printlnfo’s class 
specification for details about what information it stores. 

You can customize the PrintPanel for your application by adding a View to the panel 
through set Accessory View:. This View might contain additional controls, for 
example. If you add a View, you may need to override some of PrintPanel’s methods 
to coordinate any displays or controls you add. 


INSTANCE VARIABLES 
Inherited from Object 
Inherited from Responder 
Inherited from Window 


Class 

id 

NXRect 

id 

id 

id 

id 

id 

id 

id 

int 

int 

float 

struct _wFlags 
struct _wFlags2 


isa; 

nextResponder; 

frame; 

contentView; 

delegate; 

firstResponder; 

lastLeftHit; 

lastRightHit; 

counterpart; 

fieldEditor; 

winEventMask; 

windowNum; 

backgroundGray; 

wFlags; 

wFlags2; 
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Inherited from Panel 


(none) 


Declared in PrintPanel 


applcon 

pageMode 

firstPage 

lastPage 

copies 

ok 

cancel 

preview 

save 

change 

feed 

resolutionList 

name 

type 


id 

applcon; 

id 

pageMode; 

id 

firstPage; 

id 

lastPage; 

id 

copies; 

id 

ok; 

id 

cancel; 

id 

preview; 

id 

save; 

id 

change; 

id 

feed; 

id 

resolutionList; 

id 

name; 

id 

type; 

id 

status; 

int 

exitTag; 

id 

accessory View; 

id 

buttons; 


The Button containing the application’s icon. 

The Matrix of radio buttons indicating whether to 
print all pages or a subset. 

The Form indicating the first page to print. 

The Form indicating the last page to print. 

The TextField indicating how many copies to 
print. 

The Print Button. 

The Cancel Button. 

The Preview Button. 

Save Button. 

Change Button. 

The PopUpList of paper feed options. 

The PopUpList of resolution choices. 

The TextField for the name of the printer. 

The TextField for the type of printer. 


2-478 Chapter 2 : Class Specifications 




status 

exitTag 

accessory View 
buttons 


The TextField for the printing status. 

The tag of the button user clicked to exit the 
panel. 

The optional View added by the application. 
The Matrix of PrintPanel buttons. 


METHOD TYPES 


Creating and freeing a PrintPanel + new 

+ newContent:style:backing:buttonMask:defer: 
- free 


Customizing the PrintPanel - set Accessory View: 

- accessoryView 

Running the panel - runModal 

- pickedButton: 

Updating the panel’s display - changePrinter: 

- pickedAllPages: 

- textWillChange: 

Communicating with the Printlnfo object 

- readPrintlnfo 

- writePrintlnfo 


CLASS METHODS 

alloc 

Generates an error message. This method cannot be used to create PrintPanel 
instances; use new instead. 

See also: + new 

allocFromZone: 

Generates an error message. This method cannot be used to create PrintPanel 
instances; use new instead. 

See also: + new 
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new 


+ new 

Creates and returns the PrintPanel. This will return the existing instance of the 
PrintPanel if one has already been created. To display and run the panel, use the 
runModal method. 

See also: - runModal 

newContent:style: backing: buttonMask: defer: 

+ newContent: (const NXRect *)contentRect 
style :(int )aStyle 
backing: (int )bufferingType 

buttonMask :(int )mask 
defer:(BOOL )flag 

Used in the instantiation of the PrintPanel. You shouldn’t use this method to create the 
panel; use new instead. 

See also: + new, - runModal 


INSTANCE METHODS 


accessoryView 

- accessoryView 

Returns the View set by setAccessoryView:. 

See also: - setAccessoryView: 

changePr inter: 

- changePrintensewder 

Brings up the ChoosePrinter Panel to allow the user to select a printer. After the user 
finishes with that panel, the PrintPanel’s display is updated to reflect the newly chosen 
printer. 

free 

- free 

Frees all storage used by the PrintPanel. 
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pickedAllPages: 

- pickedAllPages:semfer 

Updates the fields for entering page numbers when the user clicks either of the radio 
buttons indicating whether to print all pages. 

pickedButton: 

- pickedButton ’.sender 

Ends the current run of this panel by sending the stopModal message to the 
Application object. This method sets the exitTag instance variable to the tag of the 
button that the user clicked to dismiss the panel (either NX_OKTAG, 

NX_CANCELTAG, NX_PREVIEWTAG, NX_SAVETAG, or NX_FAXTAG). 

See also: - stopModal (Application) 

readPrintlnfo 

- readPrintlnfo 

Reads the global Printlnfo in Application, setting the initial values of this panel. The 
number of copies is set at 1, all pages are printed, and automatic feed is chosen. 

See also: - writePrintlnfo 

runModal 

- (int)runModal 

Executes the PrintPanel. This method loads the current printing information into the 
panel from NXApp’s global Printlnfo object. It then runs the panel using 
runModalFor:. When the user finishes with the panel, it’s still displayed; you must 
hide the panel when printing is completed. If the user exits the PrintPanel with any 
button other than cancel, the information in the PrintPanel is written back to the global 
Printlnfo object. The method returns the tag of the button that the user chose to dismiss 
the panel (NX_OKTAG, NX_CANCELTAG, NX_SAVETAG, NX_PREVIEWTAG, 
or NX_FAXTAG). Note that since runModalFor: is used, the pickedButton: method 
must use the stopModal method to terminate the modal run of this panel. 

See also: + new 
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setAccessoryView: 

- setAccessory ViewraVzevv 

Adds aView to the contents of the panel. Applications use this method to add controls 
to extend the functionality of the panel. The panel is automatically resized to 
accommodate aView, which should be the top View in a view hierarchy. If aView is nil, 
then any accessory view in the panel will be removed. setAccessoryView: may be 
performed repeatedly to change the accessory view as needed. 

If controls are added, you may need to define your own version of several PrintPanel’s 
methods. For example, you may want to override pickedAllPages: to update any fields 
of information you display. Also, you may need to override readPrintlnfo and 
writePrintlnfo to get information from and write it to the global Printlnfo object. 

See also: - accessory View: 
textWIllChange: 

- (BOOL)textWillChange:textOZ?/'ect 

Ensures that the correct cell of the page mode matrix is set. Called when the user types 
in either the first page or last page field of the form. 

writePrintlnfo 

- writePrintlnfo 

Writes the values of the PrintPanel to NXApp’s global Printlnfo object. 

See also: - readPrintlnfo 
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Responder 


INHERITS FROM Object 

DECLARED IN appkit/Responder.h 

CLASS DESCRIPTION 

Responder is an abstract class that forms the basis of command and event processing in 
the Application Kit. Most Kit classes inherit from Responder. When a Responder 
object receives an event or action message that it can’t respond to—that it doesn’t have 
a method for—the message is sent to its next responder. For a View, the next responder 
is usually its superview; the content view’s next responder is the Window. Each 
Window, therefore, has its own responder chain. Messages are passed up the chain 
until they reach an object that can respond. 

Action messages and keyboard event messages are sent first to the first responder , the 
object that displays the current selection and is expected to handle most user actions 
within a window. Each Window object has its own first responder. Messages the first 
responder can’t handle work their way up the responder chain. 

This class defines the nextResponder instance variable and the methods that pass event 
and action messages along the responder chain. 


INSTANCE VARIABLES 
Inherited from Object 
Declared in Responder 
nextResponder 


Class isa; 

id nextResponder; 

The object that will be sent event messages and 
action messages that the Responder can’t handle. 


METHOD TYPES 

Managing the next responder - setNextResponder: 

- nextResponder 

Determining the first responder - acceptsFirstResponder 

- becomeFirstResponder 

- resignFirstResponder 


Aiding event processing 


- performKeyEquivalent: 

- tryToPerform: with: 
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Forwarding event messages - mouseDown: 

- rightMouseDown: 

- mouseDragged: 

- rightMouseDragged: 

- mouseUp: 

- rightMouseUp: 

- mouseMoved: 

- mouseEntered: 

- mouseExited: 

- keyDown: 

- keyUp: 

- flagsChanged: 

- noResponderFor: 

Services menu support - validRequestorForSendType:andRetumType: 

Archiving - read: 

- write: 


INSTANCE METHODS 

acceptsFirstResponder 

- (BOOL)acceptsFirstResponder 

Returns NO to indicate that, by default, Responders don’t agree to become the first 
responder. 

Before making any object the first responder, the Application Kit gives it an 
opportunity to refuse by sending it an acceptsFirstResponder message. Objects that 
can display a selection should override this default to return YES. Objects that respond 
with this default version of the method will receive mouse event messages, but no 
others. 

See also: makeFirstResponder: (Window) 

becomeFirstResponder 

- becomeFirstResponder 

Notifies the receiver that it has just become the first responder for its Window. This 
default version of the method simply returns self. Responder subclasses can implement 
their own versions to take whatever action may be necessary, such as highlighting the 
selection. 

By returning self, the receiver accepts being made the first responder. A Responder can 
refuse to become the first responder by returning nil. 
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becomeFirstResponder messages are initiated by the Window object (through its 
makeFirstResponder: method) in response to mouse-down events. 

See also: - resignFirstResponder, - makeFirstResponder: (Window) 
flagsChanged: 

- flagsChanged :(NXEvent *)theEvent 

Passes the flagsChanged: event message to the receiver’s next responder. 

keyDown: 

- keyDown :(NXEvent *)theEvent 

Passes the keyDown: event message to the receiver’s next responder. 

keyUp: 

- keyUp:(NXEvent *)theEvent 

Passes the keyUp: event message to the receiver’s next responder. 

mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Passes the mouseDown: event message to the receiver’s next responder. 

mouseDragged: 

- mouseDragged: (NXEvent *)theEvent 

Passes the mouseDragged: event message to the receiver’s next responder. 

mouseEntered: 

- mouseEntered: (NXEvent *)theEvent 

Passes the mouseEntered: event message to the receiver’s next responder. 

mouseExited: 

- mouseExited: (NXEvent *)theEvent 

Passes the mouseExited: event message to the receiver’s next responder. 
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mouseMoved: 

- mouseMoved :(NXEvent *)theEvent 

Passes the mouseMoved: event message to the receiver’s next responder. 

mouseUp: 

- mouseUp :(NXEvent *)theEvent 

Passes the mouseUp: event message to the receiver’s next responder. 

nextResponder 

- nextResponder 

Returns the receiver’s next responder. 

See also: - setNextResponder: 

noResponderFor: 

- noResponderFor: (const char *)eventType 

Handles an event message when it’s passed to the end of the responder chain and no 
object can respond. It writes a message to the system log. If the event is a key-down 
event, it generates a beep. 

performKeyEquivalent: 

- (BOOL)performKeyEquivaIent:(NXEvent *)theEvent 

Returns NO to indicate that, by default, the Responder doesn’t have a key equivalent 
and can’t respond to key-down events as keyboard alternatives. 

The Responder class implements this method so that any object that inherits from it can 
be asked to respond to a a performKeyEquivalent: message. Subclasses that define 
objects with key equivalents must implement their own versions of 
performKeyEquivalent:. If the key in theEvent matches the receiver’s key equivalent, 
it should respond to the event and return YES. 

See also: - performKeyEquivalent: (View and Button) 

read: 

- read:(NXTypedStream *)stream 

Reads the Responder from the typed stream stream. 

See also: - write: 
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resignFirstResponder 

- resignFirstResponder 

Notifies the receiver that it’s no longer the first responder for its window. This default 
version of the method simply returns self. Responder subclasses can implement their 
own versions to take whatever action may be necessary, such as unhighlighting the 
selection. 

By returning self, the receiver accepts the change. By returning nil, the receiver refuses 
to agree to the change, and it remains the first responder. 

A resignFirstResponder message is sent to the current first responder (through 
Window’s makeFirstResponder: method) when another object is about to be made the 
new first responder. 

See also: - becomeFirstResponder, - makeFirstResponder: (Window) 
rightMouseDown: 

- rightMouseDown: (NXEvent *)theEvent 

Passes the rightMouseDown: event message to the receiver’s next responder. 

r ightMouseDr agged: 

- rightMouseDragged: (NXEvent *)theEvent 

Passes the rightMouseDragged: event message to the receiver’s next responder. 

rightMouseUp: 

- rightMouseUp: (NXEvent *)theEvent 

Passes the rightMouseUp: event message to the receiver’s next responder. 

setNextResponder: 

- setNextResponder :aResponder 

Makes aResponder the receiver’s next responder. 

See also: - nextResponder 
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tryToPerform:with: 

- (BOOL)tryToPerform:(SEL)<2«Acricw withianObject 

Aids in dispatching action messages. This method checks to see whether the receiving 
object can respond to the method selector specified by anAction. If it can, the message 
is sent with anObject as an argument. Typically, anObject is the initiator of the action 
message. 

If the receiver can’t respond, tryToPerform:with: checks to see whether the receiving 
object’s next responder can. It continues to follow next responder links up the 
responder chain until it finds an object that it can send the action message to, or the 
chain is exhausted. 

Even if the receiver can respond to anAction messages, it can “refuse” them by having 
its implementation of the anAction method return nil. In this case, the message is 
passed on to the next responder in the chain. 

If successful in finding a receiver that doesn’t refuse the message, try ToPerform: 
returns YES. Otherwise, it returns NO. 

This method is used (indirectly, through the sendAction:to:from: method) to dispatch 
action messages from Control objects. You’d rarely have reason to use it yourself. 

See also: - sendAction:to:from: (Application) 

validRequestorForSendType:andReturnType: 

- validRequestorForSendType:(NXAtom)/v/?cScv2? 

andReturnType:(NXAtom)fypc/?c?wr/2c<i 

Implemented by subclasses to determine what services are available at any given time. 
In order to keep the Services menu current, the Application object sends 
validRequestorForSendType:andReturnType: messages to the first responder with 
the send and return types for each service method of every service provider. Thus, a 
Responder may receive this message many times per event. If the receiving object can 
place data of type type Sent on the pasteboard and receive data of type typeReturned 
back, it should return self; otherwise it should return nil. The Application object checks 
the return value to determine whether to enable or disable commands in the Services 
menu. 

Responder’s implementation of this method simply forwards the message to the next 
responder, so by default this method returns nil. Like untargetted action messages, 
validRequestorForSendType:andReturnType: messages are passed up the 
responder chain to the Window, then to the Window’s delegate, and finally to the 
Application object and its delegate, until an object returns self rather than nil. 

typeSent and typeReturned are pasteboard types. They’re NXAtoms, so you can 
compare them to the types your application can send and receive by comparing pointers 
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rather than comparing strings. Since this method will be invoked frequently, it must be 
as efficient as possible. 

Either typeSent or typeReturned may be NULL. If typeSent is NULL, the service 
doesn’t require data from the requesting application. If typeReturned is NULL, the 
service doesn’t return data to the requesting application. 

When the user chooses a menu item for a service, a 

writeSelectionToPasteboard:types: message is sent to the Responder (if typeSent was 
not NULL). The Responder writes the requested data to the pasteboard and a remote 
message is sent to the service. If the service’s typeReturned is not NULL, it places 
return data on the pasteboard, and the Responder receives a 

readSelectionFromPasteboard: message. 

The following example demonstrates an implementation of the 
validRequestorForSendTyperandReturnType: method for an object that can send 
and receive ASCII text. Pseudocode is in italics. 


{ 


validRequestorForSendType:(NXAtom)typeSent 

andReturnType:(NXAtom)typeReturned 


/* 


* First, check to make sure that the types are ones 

* that we can handle. 

*/ 

if ( (typeSent == NXAsciiPboardType || typeSent == NULL) && 

(typeReturned == NXAsciiPboardType || typeReturned == NULL) ) 

{ 

/* 

* If so, return self if we can give the service 

* what it wants and accept what it gives back. 

*/ 

if ( ((there is a selection) || typeSent == NULL) && 

((the text is editable) || typeReturned == NULL) ) 

{ 

return self; 

} 

} 

/* 


} 


* Otherwise, return the default. 

*/ 

return [super validRequestorForSendType:typeSent 

andReturnType .-typeReturned] ; 


See also: - registerServicesMenuSendTypesrandReturnTypes: (Application), 

- writeSelectionToPasteboarditypes: (Object Method), 

- readSelectionFromPasteboard: (Object Method) 
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write: 

- write:(NXTypedStream *)stream 

Writes the receiving Responder to the typed stream stream. The next responder is not 
explicitly written. 

See also: - read: 


2-490 Chapter 2: Class Specifications 



SavePanel 


INHERITS FROM Panel: Window : Responder : Object 

DECLARED IN appkit/SavePanel.h 

CLASS DESCRIPTION 

The SavePanel provides a simple way for an application to query the user for the name 
of a file to use when saving a document or other data. It allows the application to 
restrict the filename to have a certain file type, as specified by a filename extension. 
There is one and only one SavePanel in an application and the new method returns a 
pointer to it. 

Whenever the user actually decides on a file name, the message 
panelValidateFilename: will be sent to the SavePanel’s delegate (if it responds to that 
message). The delegate can then determine whether that file name can be used; it 
returns YES if the file name is okay, or NO if the SavePanel should stay up and wait for 
the user to type in a different file name. The delegate can also implement a 
panel:filterFile:inDirectory: method to test that both the file name and the directory 
are valid. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from Window 

NXRect 

frame; 


id 

contentView; 


id 

delegate; 


id 

firstResponder; 


id 

lastLeftHit; 


id 

lastRightHit; 


id 

counterpart; 


id 

fieldEditor; 


int 

winEventMask; 


int 

windowNum; 


float 

backgroundGray; 


struct _wFlags 

wFlags; 


struct _wFlags2 

wFlags2; 

Inherited from Panel 

(none) 
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Declared in SavePanel 


form 

browser 

okButton 

accessory View 

separator 

filename 

directory 

filenames 

requiredType 

spFlags .opening 

spFlags.exitOk 

spFlags.allowMultiple 

spFlags.dirty 

spFlags .invalidateMatrices 
spFlags.filtered 
directorySize 


id 
id 
id 
id 
id 

char 
char 

const char 
char 

struct _spFlags { 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 
unsigned int 

} 

unsigned short 
Typeable form 
The browser 
The OK button 
Application-customized area 
Line separating icon from rest 
The chosen file name 
The directory of the chosen file 
The list of chosen files 
The type of file to save 
Opening or saving 
Exit status 

Whether to allow multiple files 
Dirty flag for invisible updates 
Whether the matrices are valid 
Whether types are filtered 
Current size of directory var 


form; 
browser; 
okButton; 
accessory View; 
separator; 

* filename; 

* directory; 
**filenames; 
*requiredType; 


opening: 1; 
exitOk:l; 
allowMultiplerl; 
dirty:1; 

invalidateMatrices: 1; 
filtered: 1; 
spFlags; 
directorySize; 
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METHOD TYPES 


Creating and Freeing a SavePanel + newContent:style:backing:buttonMask:defer: 

- free 

set Accessory View: 
accessory View 
setTitle: 
setPrompt: 

setDirectory: 
setRequiredFileType: 
requiredFileType 

runModal 

runModalForDirectory :file: 

Reading Save information - directory 

- filename 

Completing a partial filename - commandKey: 

Action methods - cancel: 

- ok: 

Responding to User Input - selectText: 

- textDidGetKeys:isEmpty: 

- textDidEnd:endChar: 

Setting the delegate - setDelegate: 

- delegate (Window) 


CLASS METHODS 

newContent: style: backing: buttonMask: defer: 

+ newContent: (const NXRect *)contentRect 
style: (int)aStyle 
backing: (int )bujferingType 
buttonMask: (mt)mask 
defer :(BOOL)/?<2g 

Creates, if necessary, and returns a new instance of SavePanel. Each application shares 
just one instance of SavePanel; this method returns the shared instance if it exists. A 
simpler interface is available via the inherited method new which invokes this method 
with all the appropriate parameters. 


Customizing the SavePanel 


Setting directory and file type 


Running the SavePanel 
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INSTANCE METHODS 


accessory View 

- accessory View 

Returns the view set by setAccessoryView:. 

See also: setAccessoryView: 

alloc 

Generates an error message. This method cannot be used to create SavePanel instances. 
Use the newContent:style:backing:buttonMask:defer: method instead. 

See also: t newContent:style:backing:buttonMask:defer: 
allocFromZone: 

Generates an error message. This method cannot be used to create SavePanel instances. 
Use the newContent:style:backing:buttonMask:defer: method instead. 

See also: newContent:sty!e:baeking:buttonMask:defer: 
cancel: 

- canc thsender 

This method is the target of the Cancel button in the SavePanel. Returns self. 
commandKey: 

- (BOOL)commandKey:(NXEvent *)theEvent 

This method is used to accept command-key events. If theEvent contains a 
Command-Space, the SavePanel will do file name completion; if it contains a 
Command-H, the SavePanel jumps to the user’s home directory. Other command-key 
events are ignored. Returns YES 

directory 

- {const char *)directory 

Returns the path of the directory that the SavePanel is currently showing. 
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filename 


- (const char *)filename 

Returns the file name (fully specified) that the SavePanel last accepted. Use 
strrchr([savepanel filename], ’/’) to get the file name only (no path). 

free 

- free 

Frees all storage used by the SavePanel. 

ok: 

- ok '.sender 

This method is the target of the OK button in the SavePanel. 

requiredFileT ype 

- (const char *)requiredFileType 

Returns the last type set by setRequiredFileType:. 

run Modal 

- (int)runModal 

Displays the panel and begins its event loop. Returns 1 if successful, 0 otherwise. 

r u n Modal F or Dir ector y: file: 

- (int)runModalForDirectory: (const char *)path file:(const char *)filename 

Initializes the panel to the file specified by path and name, then displays it and begins 
its event loop. Returns 1 if successful, 0 otherwise. 

selectText: 

- selectText '.sender 

Advances the current browser selection one line when TAB is pressed (goes back one 
line when BACKTAB is pressed). 
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setAccessoryView: 

- setAccessoryView: a View 

aView should be the top View in a view hierarchy which will be added just above the 
“OK” and “Cancel” buttons at the bottom of the panel. The panel is automatically 
resized to accommodate aView. This may be called repeatedly to change the accessory 
view depending on the situation. If aView is nil, then any accessory view which is in 
the panel will be removed. 

setDelegate: 

- setDelegat eianObject 

Makes anObject the SavePanel’s delegate. Returns self. 


setDirectory: 

- setDirectory: (const char *)path 

Sets the current path in the SavePanel browser. Returns self. 


setPrompt: 

- setPrompt: (const char *)prompt 


Sets the title for the form field in which users type their entries on the panel. This title 
will appear on all SavePanels (or all OpenPanels if the receiver of this message is an 
OpenPanel) in your application. “File:” is the default prompt string. Returns self. 


setRequir edFileTy pe: 

- setRequiredFileType: (const char *)type 

Specifies the type, a file name extension to be appended to any selected files which do 
not already have that extension; for example, “nib”, type should not include the period 
which begins the extension. Be careful to invoke this method each time the SavePanel 
is used for another file type within the application. Returns self. 


setTitle: 

- setTitle:(const char *)newTitle 


Sets the title of the SavePanel to newTitle and returns self. By default, “Save” is the 
title string. If a SavePanel is adapted to other uses, its title should reflect the user action 
that brings it to the screen. 
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textDidEnd: endChar: 


- textDidEnd itextObject endChar:(unsigned short )endChar 

Determines whether the key that ended text was Tab or Shift-Tab so that selectText: 
knows whether to move forward or backwards. Returns self. 

textDidGetKeysrisEmpty: 

- textDidGetKey sitextObject isEmpty:(BOOL )flag 

Invoked by the Panel’s text to indicate whether there is any text in the Panel. Disables 
the OK button if there is no text in the Panel. 


METHODS IMPLEMENTED BY THE DELEGATE 


panel:filterFile:inDirectory: 

-(BOOL) pan ehsender 

filterFile: (const char *) filename 
inDirectory: (const char *) directory 

Sent to the panel’s delegate. The delegate can then determine whether that filename can 
be saved in the directory ; it returns YES if the filename and directory are okay, or NO 
if the SavePanel should stay up and wait for the user to type in a different file name or 
select another directory. 

panel V alidateFilenames: 

~(BOOL) panelValidateFilenames : sender 

Sent to the panel’s delegate. The delegate can then determine whether that file name 
can be used; it returns YES if the file name is okay, or NO if the SavePanel should stay 
up and wait for the user to type in a different file name. 
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Scroller 


INHERITS FROM Control: View : Responder : Object 

DECLARED IN appkit/Scroller.h 

CLASS DESCRIPTION 

The Scroller class defines a Control that’s used by a ScrollView object to position a 
document that’s too large to be displayed in its entirety within a View. A Scroller is 
typically represented on the screen by a bar, a knob, and two scroll buttons, although it 
may contain only a subset of these. The knob indicates both the position within the 
document and the amount displayed relative to the size of the document. The bar is the 
rectangular region that the knob slides within. The scroll buttons allow the user to 
scroll in small increments by clicking, or in large increments by Alternate-clicking. In 
discussions of the Scroller class, a small increment is referred to as a “line increment” 
(even if the Scroller is oriented horizontally), and a large increment is referred to as a 
“page increment,” although a page increment actually advances the document by one 
windowful. When you create a Scroller, you can specify either a vertical or a horizontal 
orientation. 

As a Control, a Scroller handles mouse events and sends action messages to its target 
(usually its parent ScrollView) to implement user-controlled scrolling. The Scroller 
must also respond to messages from a ScrollView to represent changes in document 
positioning. 

Scroller is a public class primarily for programmers who decide not to use a ScrollView 
but want to present a consistent user interface. Its use is not encouraged except in cases 
where the porting of an existing application is made more straightforward. In these 
situations, you initialize a newly created Scroller with initFrame:. Then, you use 
setTarget: (Control) to set the object that will receive messages from the Scroller, and 
you use setAction: (Control) to specify the target’s method that will be invoked by the 
Scroller. When your target receives a message from the Scroller, it will probably need 
to query the Scroller using the hitPart and float Value methods to determine what 
action to take. 

The Scroller class has several constants referring to the parts of a Scroller. A scroll 
button with an up arrow (or left arrow, if the Scroller is oriented horizontally) is known 
as a “decrement line” button if it receives a normal click, and as a “decrement page” 
button if it receives an Alternate-click. Similarly, a scroll button with a down or right 
arrow functions as both an “increment line” button and an “increment page” button. 
The constants defining the parts of a Scroller are as follows: 
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Constant 

NX_NOPART 

NX_KNOB 

NX_DECPAGE 

NX_INCPAGE 

NX_DECLINE 

NXJNCLINE 

NX_KNOBSLOT or 

NX_JUMP 


INSTANCE VARIABLES 
Inherited from Object 
Inherited from Responder 
Inherited from View 


Inherited from Control 


Declared in Scroller 


curValue 


perCent 


hitPart 

target 


Refers To 

No part of the Scroller 
The knob 

The button that decrements a page (up, left arrow) 
The button that increments a page (down, right arrow) 
The button that decrements a line (up, left arrow) 

The button that increments a line (down, right arrow) 
The bar 


Class 

isa; 

id 

nextResponder; 

NXRect 

frame; 

NXRect 

bounds; 

id 

superview; 

id 

subviews; 

id 

window; 

struct_vFlags 

vFlags; 

int 

tag; 

id 

cell; 

struct _conFlags 

ConFlags; 

float 

curValue; 

float 

perCent; 

int 

hitPart; 

id 

target; 

SEL 

action; 

struct _sFlags{ 
unsigned int 

isHorizrl; 

unsigned int 

arrowsLoc:2; 

unsigned int 

partsUsable:2; 


} sFlags; 

The position of the knob, from 0.0 (top or left 
position) to 1.0. 

The fraction of the bar the knob fills, from 0.0 to 

1 . 0 . 

Which part got the last mouse-down event. 

The target of the Scroller. 
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action 


The action sent to Scroller’s target. 


sFlags.isHoriz 

sFlags.arrowsLoc 

sFlags .partsU sable 

METHOD TYPES 

Initializing a Scroller 
Laying out the Scroller 

Setting Scroller values 

Resizing the Scroller 
Displaying 

Target and action 

Handling events 

Archiving 


True if this is a horizontal Scroller. 

The location of the scroll buttons within the 
Scroller. 

The parts of the Scroller that are currently 
displayed. 


- initFrame: 

- calcRectiforPart: 

- checkSpaceForParts 

- setArrowsPosition: 

- floatValue 

- setFloatValue: 

- setFloatValue:: 

- sizeTo:: 

- draw Arrow:: 

- drawKnob 

- drawParts 

- drawSelf:: 

- highlight: 

- set Action: 

- action 

- setTarget: 

- target 

- acceptsFirstMouse 

- hitPart 

- mouseDown: 

- testPart: 

- trackKnob: 

- trackScrollButtons: 

- awake 

- read: 

- write: 
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INSTANCE METHODS 


acceptsFirstMouse 

- (BOOL)acceptsFirstMouse 

Overrides inherited methods to ensure that the Scroller will receive the mouse-down 
event that made its window the key window. Returns YES. 

action 

- (SEL)action 

Returns the action of the Scroller—in other words, the selector for the method the 
Scroller will invoke when it receives a mouse-down event. 

See also: - target, - set Action: 

awake 

- awake 

Overrides Object’s awake method to ensure additional initialization. After a Scroller 
has been read from an archive file, it will receive this message. You should not invoke 
this method directly. Returns self. 

calcRectiforPart: 

- (NXRect *)ca!cRect:(NXRect *)aRect forPart:(ini)partCode 

Calculates the rectangle (in the Scroller’s drawing coordinates) that encloses a 
particular part of the Scroller. This rectangle is returned in aRect. partCode is 
NX_DECPAGE, NX_KNOB, NXJNCPAGE, NX_DECLINE, NXJNCLINE, or 
NX_KNOBSLOT. This method is useful if you override the drawArrow:: or 
drawKnob method. Returns aRect (the pointer you passed it). 

See also: - drawArrow::, - drawKnob 
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checkSpaceForParts 

- checkSpaceForParts 

Checks to see if there is enough room in the Scroller to display the knob and buttons 
and sets sFlags.partsUsable to one of the following values: 

Value Meaning 

NX_SCROLLERNOPARTS Scroller has no usable parts, only the bar. 

NX_SCROLLERONLYARROWS Scroller has only scroll buttons. 

NX_SCROLLERALLPARTS Scroller has all parts. 

This method is used by sizeTo::; you should not invoke this method yourself. Returns 
self. 

See also: -sizeTo:: 

draw Arrow:: 

- drawArrow:(BOOL )upOrLeft :(BOOL )highlight 

Draws a scroll button. If upOrLeft is NO, this method draws the down or right scroll 
button (NX_INCLINE), depending on whether the Scroller is oriented vertically or 
horizontally. If upOrLeft is YES, this method draws the up or left scroll button 
(NX_DECLINE). The highlight state is determined by highlight. If highlight is YES, 
the button is drawn highlighted, otherwise it’s drawn normally. This method is invoked 
by drawSelf:: and mouse-down events. It’s a public method so that you can override 
it; you should not invoke it directly. Returns self. 

See also: - drawKnob, - calcRect:forPart: 

drawKnob 

- drawKnob 

Draws the knob. Don’t send this message directly; it’s invoked by drawSelf:: and 
mouse-down events. Returns self. 

See also: - draw Arrow::, - calcRect:forPart: 

drawParts 

- drawParts 

This method caches images for the various graphic entities composing the Scroller. It’s 
invoked only once by the first of either initFrame: or awake. You may want to 
override this method if you alter the look of the Scroller, but you should not invoke it 
directly. Returns self. 
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drawSelf:: 

- drawSelf: (const NXRect *)rects :(mi)rectCount 

This method draws the Scroller. It’s used by the display methods, and you should not 
invoke it directly, rects is an array of rectangles that need to be covered, with the first 
one being the union of the subsequent rectangles. rectCount is the number of elements 
in this array. Returns self. 

See also: -display::: (View) 


float Value 

- (float)floatValue 


Returns the position of the knob, a value in range 0.0 to 1.0. A value of 0.0 indicates 
that the knob is at the top or left position within the bar, depending on the Scroller’s 
orientation. 


highlight: 

- highlight:(BOOL)/tfg 

This method highlights or unhighlights the scroll button that the user clicked on. The 
Scroller invokes this method while tracking the mouse, and you should not invoke it 
directly. If flag is YES, the button is drawn highlighted, otherwise it’s drawn normally. 
Returns self. 

See also: -drawArrow:: 


hitPart 

- (int)hitPart 

Returns the part of the Scroller that received a mouse-down event. See the Scroller 
class description for possible values. This method is typically invoked by the 
ScrollView to determine what action to take when the ScrollView receives an action 
message from the Scroller. 

See also: - action 
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initFrame: 


- initFrame: (const NXRect *)frameRect 

Initializes a new Scroller with frame frameRect, which cannot be NULL. If 
frameRecfs width is greater than its height, a horizontal Scroller is created; otherwise, 
a vertical Scroller is created. The Scroller is initially disabled. If the Scroller is a 
subview of a ScrollView, its width and height are reset automatically by the 
ScrollView’s tile method; in this case, the width of vertical Scrollers and the height of 
horizontal Scrollers are set to NX_SCROLLERWIDTH. This method is the designated 
initializer for the Scroller class. Returns self. 

See also: - setEnabled: (Control), - tile (ScrollView), + alloc (Object), 

+ allocFromZone: (Object) 

mouseDown: 

- mouseDown: (NXEvent *)theEvent 

This method acts as a dispatcher when a mouse-down event occurs in the Scroller. It 
determines what part of the Scroller was clicked, and invokes the appropriate methods 
(such as trackKnob: or trackScrollButtons:). You should not invoke this method 
directly. Returns self. 

read: 

- read:(NXTypedStream *)stream 

Reads the Scroller from the typed stream stream , and sets all aspects of its state. 
Returns self. 

See also: - write: 

set Action: 

- setAction:(SEL)<zSe/ector 

Sets the action of the Scroller. When the user manipulates the Scroller, the Scroller 
sends its action message to its target, which (if it’s a ScrollView) will then query the 
Scroller to determine how to respond. Returns self. 

See also: -setTarget:,-action 
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set Ar rowsPosition: 

- setArrowsPosition:(int)wAere 

Sets the location of the scroll buttons within the Scroller to where , or inhibits their 
display, as follows: 

Value 

NX_SCROLLARROWSMAXEND 
NX_SCROLLARROWSMINEND 
NX_S CROLL ARROW S NONE 

Returns self. 

setFloatValue: 

- setFloatValue \(1hoa.t)aFloat 

Sets the position of the knob to aFloat , which is a value between 0.0 and 1.0. This 
method is the same as setFloatValue:: except it doesn’t change the size of the knob. 
Returns self. 

See also: - setFloatValue:: 

setFloatValue:: 

- setFloatValue :(fioat)aFloat ‘.(float )knobProportion 

Sets the position and size of the knob. Sets the position within the bar to aFloat, which 
is a value between 0.0 and 1.0. A value of 0.0 positions and displays the knob at the 
top or left of the bar, depending on the orientation of the Scroller. The size of the knob 
is determined by knobProportion, which is a value between 0.0 and 1.0. A value of 0.0 
sets the knob to a predefined minimum size, and a value of 1.0 makes the knob fill the 
bar. Returns self. 

See also: - setFloatValue: 

setTarget: 

- setTargetianObject 

Sets the target of the Scroller. The Scroller’s target receives the action message set by 
set Action: when the user manipulates the Scroller. Returns self. 

See also: - target, - setAction: 


Meaning 

Buttons at bottom or right 
Buttons at top or left 
No buttons 
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sizeTo:: 

- sizeTo: (NXCoord )width :(NXCoord )height 

Overrides the default View method so the Scroller can check which parts can be drawn. 
This method is typically invoked by tile (ScrollView), which sets the Scroller to a 
constant width (or height, if the Scroller is horizontal) of NX_SCROLLERWIDTH. 
Returns self. 

See also: - checkSpaceForParts, - tile (ScrollView) 

target 

- target 

Returns the Scroller’s target. 

See also: - setTarget:, - action 

testPart: 

- (int)testPart: (const NXPoint *)the Point 

Returns the part of the Scroller that lies under thePoint. See the Scroller class 
description for possible values. 

trackKnob: 

- trackKnob :(NXEvent *)t he Event 

Tracks the knob and sends action messages to the Scroller’s target. This method is 
invoked when the Scroller receives a mouse-down event in the knob. You should not 
invoke this method directly. Returns self. 

See also: - mouseDown:, - action, - target 

trackScrollButtons: 

- trackScrollButtons :(NXEvent *)theEvent 

Tracks the scroll buttons and sends action messages to the Scroller’s target. This 
method is invoked when the Scroller receives a mouse-down event in a scroll button. 
You should not invoke this method directly. Returns self. 

See also: - mouseDown:, - action, - target 
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write: 

- write :(NXTypedStream *)stream 

Writes the Scroller to the typed stream stream, saving all aspects of its state. Returns 
self. 

See also: -read: 


CONSTANTS AND DEFINED TYPES 

/* Location of scroll buttons within the Scroller */ 


#define NX_SCROLLARROWSMAXEND 0 

#define NX_SCROLLARROWSMINEND 1 

#define NX_SCROLLARROWSNONE 2 

/* Usable parts in the Scroller */ 

#define NX_SCROLLERNOPARTS 0 

#define NX_SCROLLERONLYARROWS 1 

#define NX_SCROLLERALLPARTS 2 

/* Part codes for various parts of the Scroller */ 

#define NX_NOPART 0 

#define NX_DECPAGE 1 

#define NX_KNOB 2 

#define NX_INCPAGE 3 

#define NX_DECLINE 4 

#define NX_INCLINE 5 

#define NX_KNOBSLOT 6 

#define NX_JUMP 6 

#define NX SCROLLERWIDTH (18.0) 
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ScrollView 


INHERITS FROM View : Responder : Object 

DECLARED IN appkit/ScrollView.h 

CLASS DESCRIPTION 

The purpose of the ScrollView class is to allow the user to interact with a document that 
is too large to be represented in its entirety within a View and must therefore be 
scrolled. The responsibility of a ScrollView is to coordinate scrolling behavior between 
Scroller objects and a Clip View object. Thus, the user may drag the knob of a Scroller 
and the ScrollView will send a message to its Clip View to ensure that the viewed 
portion of the document reflects the position of the knob. Similarly, the application can 
change the viewed position within a document and the ScrollView will send a message 
to the Scrollers advising them of this change. 

The ScrollView has at least one subview (a Clip View object), which is called the 
content view. The content view in turn has a subview called the document view , which 
is the view to be scrolled. When a ScrollView is created, it has neither a vertical nor a 
horizontal scroller, and the content view is sized to fill the ScrollView. If Scrollers are 
required, the application must send the setVertScrollerRequired:YES and 
setHorizScrollerRequired: YES messages to the ScrollView, and the content view is 
resized to fill the area of the ScrollView not occupied by the Scrollers. These two 
methods only set flags for the ScrollView; if the flag is YES, the ScrollView will 
automatically enable and disable the Scroller as required to allow the user to scroll 
through the entire document. In other words, if the vertical scroller flag is set to YES 
and the document view grows beyond the vertical bounds of the Clip View, the 
ScrollView will enable the vertical Scroller. 

When a Scroller is required, the application must send the appropriate message to the 
ScrollView (setVertScrollerRequired; or setHorizScroller Required:). The 
ScrollView will then create a new Scroller instance, make the Scroller a subview of the 
ScrollView, and set itself as the Scroller’s target. When the ScrollView receives an 
action message from the Scroller, it queries the Scroller to determine what action to 
take, and then it sends a message to the content view telling it to scroll itself to the 
appropriate position. Similarly, when the application modifies the scroll position 
within the document, it should send a reflectScroll: message to the ScrollView, which 
will then query the content view and set the Scroller(s) accordingly. The reflectScroll: 
message may also cause the ScrollView to enable or disable the Scrollers as required. 
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INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 

Declared in ScrolIView 

id 

vScroller; 


id 

hScroller; 


id 

contentView; 


float 

pageContext; 


float 

lineAmount; 

vScroller 

The vertical scroller. 


hScroller 

The horizontal scroller. 


contentView 

The content view. 


pageContext 

The amount from the previous page (in the 
content view’s coordinates) remaining in the 
content view after a page scroll. 

lineAmount 

The number of units (in the content view’s 
coordinates) to scroll for a line scroll. 


METHOD TYPES 


Initializing a ScrolIView 

- initFrame: 


Determining component sizes - getContentSize: 

- getDocVisibleRect: 

Laying out the ScrolIView + getContentSize:forFrameSize:horizScroiler: 

vertScroller.borderType: 

+ getFrameSize:forContentSize:horizScroller: 
vertScroller.borderType: 

- resizeSubviews: 

- setHorizScrollerRequired: 

- setVertScrolierRequired: 

- tile 
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Managing component Views 

- setDocView: 

- docView 

- setHorizScroller: 

- horizScroller 

- set VertScroller: 

- vertScroller 

- reflectScroll: 

Modifying graphic attributes 

- setBorderType: 

- borderType 

- setBackgroundGray: 

- backgroundGray 

- setBackgroundColor: 

- backgroundColor 

Setting scrolling behavior 

- setCopyOnScroll: 

- setDisplayOnScroll: 

- setDynamicScrolling: 

- setLineScroll: 

- setPageScroll: 

Displaying 

- drawSelf:: 

Managing the cursor 

- setDocCursor: 

Archiving 

- read: 

- write: 


CLASS METHODS 


getContentSize:forFrameSize:horizScroller:vertScroller:borderType: 

+ getContentSize:(NXSize *)cSize 

forFrameSize: (const NXSize *)fSize 
horizScroller : (BOOL) hF lag 
vertScroller : (BOOL )vFlag 
borderType: (mt)aType 

Calculates the size of a content view for a Scroll View with frame siz efSize. hFlag is 
YES if the ScrollView has a horizontal scroller, and vFlag is YES if it has a vertical 
scroller. aType indicates whether there’s a line, a bezel, or no border around the frame 
of the ScrollView, and is NXJLINE, NX_BEZEL, or NX_NOBORDER. The content 
view size is placed in the structure specified by csize. If the ScrollView object already 
exists, you can send it a getContentSize: message to get the size of its content view. 
Returns self. 

See also: 

+ getFrameSize:forContentSize:horizScroller:vertScroller:borderType:, 

- getContentSize: 
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getFrameSize:forContentSize:horizScroller:vertScroIIer:borderType: 

+ getFrameSize:(NXSize *)fSize 

forContentSize: (const NXSize *)cSize 
hor izScroller : (B OOL) hFlag 
ver tScroller : (BOOL )vFlag 
borderType: (int)aType 

Calculates the size of the frame required for a ScrollView with a content view size 
cSize. The required frame size is placed in the structure specified by /Size. hFlag is 
YES if the ScrollView has a horizontal scroller, and vFlag is YES if it has a vertical 
scroller. aType indicates whether there’s a line, a bezel, or no border around the frame 
of the ScrollView, and is NX_LINE, NX_BEZEL, or NX_NOBORDER. Returns self. 

See also: 

+ getContentSize: forFrameSize: horizScrolIer: vertScroIIer ‘.border Type:, 

- getContentSize: 


INSTANCE METHODS 


backgroundColor 

- (NXColor)backgroundColor 

Returns the color of the content view’s background. This method simply invokes the 
content view’s backgroundColor method. 

See also: - setBackgroundColor:, - backgroundGray, 

- backgroundColor (ClipView) 

backgroundGray 

- (float)backgroundGray 

Returns the gray value of the content view’s background, a float from 0.0 (black) to 1.0 
(white). This method simply invokes the content view’s backgroundGray method. 

See also: - setBackgroundGray:, - backgroundColor, 

- backgroundGray (ClipView) 

borderType 

- (int)borderType 

Returns a value representing the type of border surrounding the ScrollView. The 
possible values for the border type are NXJLINE, NX_BEZEL, and 
NX.NOBORDER. 

See also: - setBorderType: 
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doc View 


- docView 

Returns the current document view by sending the ScrollView’s content view a 
docView message. 

See also: - setDocView:, - docView (ClipView) 

drawSelf:: 

- drawSelf: (const NXRect *)rects :(int )rectCount 

This method draws the ScrollView. It does not draw the ScrollView’s subviews, rects 
is an array of rectangles that need to be covered, with the first one being the union of 
the subsequent rectangles. rectCount is the number of elements in this array. You may 
want to override this method if you’ve subclassed the ScrollView to manage additional 
subviews and if other separation lines need to be drawn. Returns self. 

See also: - borderType, - display::: (View) 


getContentSize: 

- getContentSize:(NXSize *)theSize 

Places the size of the ScrollView’s content view in the structure specified by the Size. 
theSize is specified in the coordinates of the ScrollView’s superview. Returns self. 

See also: + getContentSize:forFrameSize:horizScroller:vertScroller:borderType: 

getDocV isibleRect: 

- getDocVisibleRect: (NXRect *)aRect 

Gets the portion of the document view visible within the ScrollView’s content view. 
The content view’s bounds rectangle, transformed into the document view’s 
coordinates, is placed in the structure specified by aRect. This rectangle represents the 
portion of the document view’s coordinate space that’s visible through the ClipView. 
However, the rectangle doesn’t reflect the effects of any clipping that may occur above 
the ClipView itself. Thus, if the ClipView is itself clipped by one of its superviews, this 
method returns a different rectangle than the one returned by the getVisibleRect: 
method, because the latter reflects the effects of all clipping by superviews. Returns 
self. 

See also: - getDocVisibleRect: (ClipView), - getVisibleRect: (View) 
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horizScroller 


- horizScroller 

Returns the horizontal scroller, a Scroller object. This method is provided for the rare 
case where sending a message directly to the Scroller is desired. 

See also: - vertScroller 

initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes the Scroll View, which must be a newly allocated Scroll View instance. The 
Scroll View’s frame rectangle is made equivalent to that pointed to by frameRect, which 
is expressed in the ScrollView’s superview’s coordinates. This method installs a 
Clip View as its content view. Clipping is set to NO by a setClipping: message (the 
ScrollView relies on the content view for clipping), opacity is set to YES by a 
setOpaque: message, and auto-resizing of its subview is set to YES by a 
setAutoresizeSubviews: message. When created, the ScrollView has no Scrollers, and 
its content view fills its bounds rectangle. This method is the designated initializer for 
the ScrollView class, and can be used to initialize a ScrollView allocated from your own 
zone. Returns self. 

See also: + alloc (Object), + allocFromZone: (Object), 

- setHorizScrollerRequired:, - setVertScrollerRequired:, - setLineScroll:, 

- setPageScroll: 

read: 

- read:(NXTypedStream *) stream 

Reads the ScrollView from the typed stream stream. This method reads the ScrollView, 
its scrollers, and its content view, which in turn causes the content view’s document 
view to be read. Returns self. 

See also: - write: 

reflectScroIl: 

- reflectScrolh.cV/CH 

Determines the new settings for the Scrollers by looking at the relationship between the 
content view’s bounds and the document view’s frame, and sends the Scrollers a 
setFloatValue:: message. If the appropriate extent of the document view’s frame is 
less than or equal to that of the content view’s bounds, the corresponding Scroller is 
disabled. Returns self. 

See also: - setFloatValue:: (Scroller) 


2-514 Chapter 2: Class Specifications 



resizeSubviews: 


- resizeSubviews: (const NXSize *)oldSize 

Overrides View’s resizeSubviews: to retile the Scroll View. This method is invoked 
when the ScrollView receives a sizeTo:: message. Returns self. 

See also: - tile 

setBackgroundColor: 

- setBackgroundColor :(NXColor)co/or 

Sets the color of the content view’s background. This color is used to paint areas inside 
the content view that aren’t covered by the document view. This method simply 
invokes the content view’s setBackgroundColor: method. Returns self. 

See also: - backgroundColor, - setBackgroundGray:, - setBackgroundColor: 

(Clip View) 

setBackgroundGray: 

- setBackgroundGray:(float)v<2/Mc 

Sets the gray value of the content view’s background. This gray is used to paint areas 
inside of the content view that aren’t covered by the document view, value must be in 
the range from 0.0 (black) to 1.0 (white). To specify one of the four pure shades of gray, 
use one of these constants: 

Constant Shade 

NXJWHITE White 

NX.LTGRAY Light gray 

NX_DKGRAY Dark gray 

NX_BLACK Black 

This method simply invokes the content view’s setBackgroundGray: method. 
Returns self. 

See also: - backgroundGray, - setBackgroundColor:, 

- setBackgroundGray: (ClipView) 

setBorderType: 

- setBorderType :(int)aType 

Determines the border type of the ScrollView. aType must be NX_NOBORDER, 
NX_LINE, or NX_BEZEL. The default is NX_NOBORDER. Returns self. 

See also: - borderType 
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setCopyOnScroIl: 

- setCopyOnScroIl :(BOOL)/7ag 

Determines whether the bits on the screen will be copied when scrolling occurs. If flag 
is YES, scrolling will copy as much of a view’s bitmap as possible to scroll the view. 
If flag is NO, the entire content view will always be redrawn to perform a scroll. This 
should only rarely be changed from the default value (YES). This method simply 
invokes the content view’s setCopyOnScroIl: method. Returns self. 

See also: - setCopyOnScroIl: (ClipView) 

setDisplayOnScroll: 

- set Display On Scroll:(BOOL)//<3^ 

Determines whether the results of scrolling will be immediately displayed. If flag is 
YES, the results of scrolling will be immediately displayed. If flag is NO, the Clip View 
is marked as invalid but is not displayed. The ScrollView may then be updated by 
sending it a display message. This should only rarely be changed from the default 
value (YES). This method simply invokes the content view’s setDisplayOnScroll: 
method. Returns self. 

See also: - setDisplayOnScroll: (ClipView), - display (View), - invalidate (View) 

setDocCursor: 

- setDocCursor:<2/?(3/?/ 

Sets the cursor to be used inside the content view by sending a setDocCursor: message 
to the content view. Returns the old cursor. 

See also: - setDocCursor: (ClipView) 

setDocView: 

- setDoc Vie w :<2 View 

Attaches the document view to the ScrollView. There is one document view per 
ScrollView, so if there was already a document view for this ScrollView it is replaced. 
A ScrollView is initialized without a document view. This method simply invokes the 
content view’s setDocView: method. Returns the old document view, or nil if there 
was none. 

See also: - doc View, - setDocView: (Clip View) 
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setDynamicScrolling: 

- setDynamicScrolling:(BOOL)/ag 

Determines whether dragging a scroller’s knob will result in dynamic redisplay of the 
document. If flag is YES, scrolling will occur as the knob is dragged. If flag is NO, 
scrolling will occur only after the knob is released. By default, scrolling occurs as the 
knob is dragged. Returns self. 

setHorizScroller: 

- setHorizScroller :anObject 

Sets the horizontal scroller to an instance of a subclass of Scroller. You will rarely need 
to invoke this method. This method sets the target of anObject to the ScrollView and 
sets anObject's action to the ScrollView’s private method that responds to the Scrollers 
and invokes the appropriate scrolling behavior. To make the scroller visible, you must 
have previously sent or must subsequently send a setHorizScrollerRequired:YES 
message to the ScrollView. Returns the old scroller. 

See also: - setVertScroller: 

setHorizScrollerRequired: 

- setHorizScrollerRequired: (BOOL )flag 

Adds or removes a horizontal scroller for the ScrollView. If flag is YES, the ScrollView 
creates a new Scroller and resizes its other subviews to make space for the Scroller. If 
flag is NO, the Scroller is removed from the ScrollView and the other subviews are 
resized to fill the ScrollView. When a ScrollView is created, it does not have a 
horizontal scroller. Once a Scroller is added, it will be enabled and disabled 
automatically by the ScrollView. This method retiles and redisplays the ScrollView. 
Returns self. 

See also: - tile 

setLineScrolI: 

- setLineScrolI: (float )value 

Sets the amount to scroll the document view when the ScrollView receives a message 
to scroll one line, value is expressed in the content view’s coordinates. Returns self. 

See also: - setPageScroll: 
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setPageScrolI: 

- setPageScrolI: (float )value 

Sets the amount to scroll the document view when the ScrollView receives a message 
to scroll one page, value is the amount common to the content view before and after 
the page scroll and is expressed in the content view’s coordinates. Therefore, setting 
value to 0.0 implies that the entire content view is replaced when a page scroll occurs. 
Returns self. 

See also: - setLineScroll: 

setVertScroller: 

- setVertScroller:<2«0£>/<?<:/ 

Sets the vertical scroller to an instance of a subclass of Scroller. You will rarely need 
to invoke this method. This method sets the target of anObject to the ScrollView and 
sets anObjecf s action to the ScrollView’s private method that responds to the Scrollers 
and invokes the appropriate scrolling behavior. To make the scroller visible, you must 
have previously sent or must subsequently send a setHorizScroIlerRequirediYES 
message to the ScrollView. Returns the old scroller. 

See also: - setHorizScroller: 

set V ertScroIlerRequired: 

- setVertScroIlerRequired: (BOOL )flag 

Adds or removes a vertical scroller to the ScrollView. If flag is YES, the ScrollView 
creates a new Scroller and resizes its other subviews to make space for the Scroller. If 
flag is NO, the Scroller is removed from the ScrollView and the other subviews are 
resized to fill the ScrollView. When a ScrollView is created, it does not have a vertical 
scroller. Once a Scroller is added, it will be enabled and disabled automatically by the 
ScrollView. This method retiles and redisplays the ScrollView. Returns self. 

See also: - tile 
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tile 


- tile 

Tiles the subviews of the ScrollView. You never send a tile message directly, but you 
may override it if you need to have the ScrollView manage additional views. When tile 
is invoked, it’s responsible for sizing each of the subviews of the ScrollView, including 
the content view. This is accomplished by sending each of its subviews a setFrame: 
message. The width of the vertical scroller and the height of the horizontal scroller (if 
present) are set to NX_SCROLLERWIDTH. A tile message is sent whenever the 
ScrollView is resized, or a vertical or horizontal scroller is added or removed. The 
method invoking tile should then send a display message to the ScrollView. Returns 
self. 

See also: - setVertScrollerRequired:, - setHorizScrollerRequired:, 

- resizeSubviews: 

vertScroller 

- vertScroller 

Returns the vertical scroller, a Scroller object. This method is provided for the rare case 
where sending a message directly to the scroller is required. 

See also: - horizScroller 
write: 

- write: (NXTypedStream *)stream 

Writes the ScrollView to the typed stream stream. This method writes the ScrollView, 
its scrollers, and its content view, which in turn causes the content view’s document 
view to be written. Returns self. 

See also: -read: 
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SelectionCell 



INHERITS FROM 

Cell: Object 


DECLARED IN 

appkit/SelectionCell.h 


CLASS DESCRIPTION 



SelectionCell is a subclass of Cell used to implement the visualization of hierarchical 
lists of names. If the cell is a leaf, it displays its text only; otherwise it also displays a 
right arrow, similar to the way MenuCell indicates submenus. 

INSTANCE VARIABLES 



Inherited from Object 

Class 

isa; 

Inherited from Cell 

char 

^contents; 


id 

support; 


struct _cFlagsl 

cFlagsl; 


struct _cFlags2 

cFlags2; 

Declared in SelectionCell 

(none) 


METHOD TYPES 



Initializing a new SelectionCell 

- init 

- initTextCell: 


Querying Component Sizes 

- calcCellSize:inRect: 


Querying the SelectionCell 

- isOpaque 

- setLeaf: 


Modifying the SelectionCell 

- isLeaf 


Displaying 

- drawInsiderinView: 

- drawSelf:inView: 

- highlight:inView:lit: 


Archiving 

- awake 
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INSTANCE METHODS 


awake 

- awake 

Caches the arrow bitmaps, if they aren’t already and returns the receiver, a newly 
unarchived instance of SelectionCell. You don’t invoke this method; it is invoked as 
part of the read method used to unarchive objects from typed streams. 

calcCellSize:inRect: 

- calcCellSize:(NXSize *)theSize inRect:(const NXRect *)aRect 

Returns, by reference, the minimum width and height required for displaying the 
SelectionCell in aRect. Leaves enough space for a menu arrow. 

drawInsideiinView; 

- drawlnside: (const NXRect *)cellFrame in View icontrolView 

Displays the SelectionCell within cellFrame in controlView. You never invoke this 
method directly; it is invoked by the drawSelf method of controlView. Override this 
method if you create a subclass of SelectionCell that does its own drawing. 


drawSelf:inView: 

- drawSelf; (const NXRect *)cellFrame inYievr.controlView 

Simply invokes drawInside:inView: since the SelectionCell has nothing to draw 
except its insides. You never invoke this method directly; it is invoked by the drawSelf 
method of controlView. 

highlight:inView:lit: 

- highlight: (const NXRect *)cellFrame 

mV \evr. controlView 
lit: (BOOL )flag 

Highlights the cell within cellFrame in controlView if flag is YES, unhighlights it if flag 
is NO. Returns self. 


init 

- init 

Initializes and returns the receiver, a new instance of SelectionCell, with the title 
“Listltem.” The new instance is set as a leaf. 

See also: - setLeaf: 
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initTextCell: 


- initTextCell: (const char *)aString 

Initializes and returns the receiver, a new instance of SelectionCell, with aString as its 
title. The new instance is set as a leaf. This method is the designated initializer for 
SelectionCell; override this method if you create a subclass of SelectionCell that 
performs its own initialization. 

See also: - setLeaf: 

isLeaf 

- (BOOL)isLeaf 

Returns YES if the cell is a leaf, NO otherwise. If the cell is a leaf, it displays its text 
only, otherwise it also displays a right arrow like that MenuCell displays to indicate 
submenus 

See also: - setLeaf: 

isOpaque 

- (BOOL)isOpaque 

Returns YES since SelectionCells touch all the bits in their frame. 

setLeaf: 

- setLeaf:(BOOL)/ 7 <zg 

If flag is YES, sets the Cell to be a leaf, if NO, sets it to be a branch. Leaf SelectionCells 
display text only; branch SelectionCells also displays a right arrow like that displayed 
by MenuCell to indicate submenu entries. Returns self. 

See also: - isLeaf: 
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Slider 


INHERITS FROM Control: View : Responder : Object 

DECLARED IN appkit/Slider.h 

CLASS DESCRIPTION 

Sliders are Controls that have a sliding knob that can be moved to represent a value 
between a minimum and a maximum. The action of the Slider can be sent continuously 
to the target by invoking setContinuous: (YES is the default). 

Slider (and an accompanying SliderCell) can be dragged into your application from 
Interface Builder’s Palettes panel. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

NXRect 

id 

id 

id 

struct_vFlags 

frame; 

bounds; 

superview; 

subviews; 

window; 

vFlags; 

Inherited from Control 

int 

id 

struct _conFlags 

tag; 

cell; 

conFlags; 

Declared in Slider 

(none) 


METHOD TYPES 



Initializing the Slider Class Objects 

+ setCellClass: 


Initializing a new Slider instance 

- initFrame: 


Setting Slider Values 

- max Value 

- min Value 

- setMaxValue: 

- setMinValue: 


Enabling the Slider 

- setEnabled: 
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Resizing the Slider 


- sizeToFit 


Handling Events - acceptsFirstMouse 

- mouseDown: 

CLASS METHODS 

setCellClass: 

+ setCellClass:c/ass/d 

Sets the subclass of SliderCell that’s used in implementing all Sliders. The default is 
SliderCell. classld should be the value returned by sending a class message to 
SliderCell or a subclass of SliderCell. Returns the id of the Slider class object. 


INSTANCE METHODS 


acceptsFirstMouse 

- (BOOL)acceptsFirstMouse 

Returns YES since Sliders always accept first mouse. 

initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes and returns the receiver, a new instance of Slider. The Slider will be 
horizontal if frameRect is wider than it is high; otherwise it will be vertical. By default, 
the Slider is continuous. After initializing the Slider, invoke the sizeToFit method to 
resize the Slider to accommodate its knob. This method is the designated initializer for 
the Slider class. 


maxValue 

- (double)max Value 

Returns the maximum value of the Slider. 

min Value 

- (double)min Value 

Returns the minimum value of the Slider. 
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mouseDown: 

- mouseDown: (NXEvent *)theEvent 

Sends a trackMouse:inRect:ofView: message to the Slider’s cell. Returns self. 

setEnabled: 

- setEnabled:(BOOL)/fag 

If flag is YES, enables the Slider; if NO, disables the Slider. Redraws the interior of the 
Slider if autodisplay is on and the enabled state has changed. Returns self. 

setMaxValue: 

- setMaxValue:(double)aD<9M&/e 

Sets the maximum value of the Slider and returns self. 

setMinValue: 

- setMinValue :(doub\e)aDouble 

Sets the minimum value of the Slider and returns self. 

sizeToFit 

- sizeToFit 

The Slider is sized to fit its cell, and its width is adjusted so that its knob fits exactly in 
its border. Returns self. 
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SliderCell 


INHERITS FROM 


ActionCell: Cell: Object 


DECLARED IN 


appkit/SliderCell.h 


CLASS DESCRIPTION 

The SliderCell is used to implement the Slider Control as well as to provide Matrices 
of SliderCells. The trackRect is the rectangle inside which tracking occurs-the 
interior of the bezeled area in which the Slider’s knob slides. 


INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Cell 

char 

^contents; 


id 

support; 


struct _cFlagsl 

cFlagsl; 


struct _cFlags2 

cFlags2; 

Inherited from ActionCell 

int 

tag; 


id 

target; 


SEL 

action; 

Declared in SliderCell 

double 

value; 


double 

maxValue; 


double 

minValue; 


NXRect 

trackRect; 

value 

The current value of the slider 

maxValue 

The maximum allowable value of the 

minValue 

The minimum allowable value of the 

trackRect 

The interior tracking area 


METHOD TYPES 

Initializing a new SliderCell - init 

Determining Component Sizes - calcCellSizerinRect: 

- getKnobRect: flipped: 
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Setting SliderCell Values - double Value 

- float Value 

- int Value 

- max Value 

- min Value 

- setDouble Value: 

- setFloatValue: 

- setlntValue: 

- setMaxValue: 

- setMinValue: 

- setStringValue: 

- string Value 

Modifying Graphic Attributes - isOpaque 

Displaying - drawBarInside:flipped: 

- drawInside:inView: 

- drawKnob 

- drawKnob: 

- drawSelf:inView: 


Target and Action 


Tracking the Mouse 


Archiving 


- isContinuous 

- setContinuous: 

- continueTracking:at:inView: 

+ prefersTrackingUntilMouseUp 

- startTrackingAt:inView: 

- stopTracking:at:inView:mouseIsUp: 

- trackMouse:inRect:ofView: 

- awake 

- read: 

- write: 


CLASS METHODS 

prefersTrackingUntilMouseUp 

+ (BOOL)prefersTrackingUntilMouseUp 

Returns YES to enable a SliderCell instance, after a mouse-down event, to track 
mouse-dragged and mouse-up events even if they occur outside its frame. This ensures 
that a SliderCell in a matrix doesn’t stop responding to user input (and its neighbor start 
responding) just because the knob isn’t dragged in a perfectly straight line. Override 
this method to allow a SliderCell to stop tracking if the mouse moves outside its frame 
after a mouse-down event. 
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INSTANCE METHODS 


awake 

- awake 

Reinitializes the receiver’s NXImageReps upon unarchiving. 

calcCellSize:inRect: 

- calcCelLSize:(NXSize *)theSize inRect:(const NXRect *)aRect 

If the width of aRect is greater than its height then the SliderCell will be horizontal in 
which case theSize->width returned will be the same as aRect->width and 
theSize->height will be the height of the SliderCell bar. Otherwise, the SliderCell will 
be vertical, and the height will be the same as aRect->height and the width will be the 
width of the bar. Note that it is usually wrong to invoke calcCellSize: without the 
inRect: on a SliderCell. 

Override this if you draw a different knob on the SliderCell (or if you draw the 
SliderCell itself differently). You must also override getKnobRect.'flipped: and 
drawKnob:. 

continueTracking:at:inView: 

- (BOOL)continueTracking: (const NXPoint *)lastPoint 

at: (const NXPoint *)currentPoint 
inYievr.controlView 

Continues tracking by moving the knob to currentPoint. Always returns YES. Invokes 
getKnobRect:flipped: to get the current location of the knob and drawKnob to draw 
the new position. Override this if you want to change the way positioning is done (e.g., 
if you wanted to add fine positioning with the ALTERNATE key). 

double Value 

- (double)doubleValue 

Returns the value of the SliderCell. 

drawBar Inside: flipped: 

- drawBarlnside: (const NXRect *)cellFrame flipped:(BOOL)flipped 

Draws the slider bar. Override this method if you want to draw your own slider bar. 
See also: - drawSelf:inView: 
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drawInside:inView: 

- drawlnside: (const NXRect *)cellFrame in View icontrolView 
Same as drawSelf:inView:, but doesn’t draw the bezel. 

See also: - drawSelf:inView: 

drawKnob 

- drawKnob 

Draws the knob. You never override this method; override drawKnob: instead. 
drawKnob: 

- drawKnob: (const 'NXRect*)knobRect 

Draws the knob in knobRect. You must override this method if you want to draw your 
own knob (as well as getKnobRect.’flipped: and maybe caIcCeIlSize:inRect:). 

drawSelfrinView: 

- dr awSelf: (const NXRect *)cellFrame in View icontrolView 

Draws the SliderCell bar and knob. The knob is drawn at a position which reflects the 
current value of the SliderCell. This drawSelf:inView: doesn’t invoke 
drawInside:inView:. 

This method invokes calcCeIlSize:inRect: and centers the resulting sized rectangle in 
cellFrame, draws the bezel, fills the bar with LTGRAY if the cell is disabled, and 0.5 
gray if not, then invokes drawKnob. 

If, for example, you wanted a SliderCell which could be any size, you simply have 
calcCellSize:inRect: return whatever size you deem appropriate, override 
getKnobRect:flipped: to return the correct rectangle to draw the knob in, and 
drawKnob: so that an appropriate knob is drawn. 

float Value 

- (float)float Value 

Returns the value of the SliderCell as a float. 
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getKnobRect:flipped: 

- getKnobRect:(NXRect*)£noWtect flipped:(BOOL )flipped 

This method must be overridden if you do your own knob (as well as drawKnob: and 
maybe calcCellSize:inRect:). It returns the rectangle into which the knob will be 
drawn based on value, min Value, max Value and trackRect (the interior tracking 
rectangle of the SliderCell). Remember to take into account the flipping of the target 
view (in flipped) in vertical SliderCells. 


init 


- init 


Initializes and returns the receiver, a new instance of SliderCell. The value is set to 0.0, 
the min Value is set to 0.0, the max Value is set to 1.0, and the SliderCell is continuous. 

This method is the designated initializer for SliderCell; override this method if you 
create a subclass of SliderCell that performs its own initialization. SliderCell doesn’t 
override the Cell class’s designated initializer initlconCell:; don’t use that method to 
initialize a SliderCell. 

See also: - setContinuous:, - setMaxValue:, - setMinValue: 

intValue 

- (int)intValue 

Returns the value of the SliderCell as an int. 

isContinuous 

- (BOOL)isContinuous 

Returns YES if action message is sent to the target object continuously as 
mouse-dragged events occur in the Cell; NO if the action is sent periodically or only on 
mouse-up events. 

isOpaque 

- (BOOL)isOpaque 

Returns YES since all SliderCells are opaque. 

maxValue 

- (double)max Value 

Returns the maximum value of the SliderCell. 

See also: - setMaxValue: 
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min Value 


- (double)min Value 

Returns the minimum value of the SliderCell. 

See also: - setMinValue: 

read: 

- read:(NXTypedStream *)stream 

Reads the SliderCell from the typed stream stream. Returns self. 

setContinuous: 

- setContinuous:(BOOL)/7tfg 

If flag is YES, sets the SliderCell so that it sends its action message to its target object 
continuously as mouse-dragged events occur in it. If NO, then the SliderCell sends its 
action message to its target object only when a mouse-up event occurs. Returns self. 

setDouble Value: 

- setDoubleValue: (double)aDouble 

Sets the value of the SliderCell to aDouble. Updates the SliderCell knob position to 
reflect the new value and returns self. 

setFloatValue: 

- setFloatValue: (fioai)aFloat 

Sets the value of the SliderCell to aFloat. Updates the SliderCell knob position to 
reflect the new value and returns self. 

setlntValue: 

- setlntValue :(mt)anlnt 

Sets the value of the SliderCell to anlnt. Updates the SliderCell knob position to reflect 
the new value and returns self. 

setMaxValue: 

- setMaxValue :(doub\e)aDouble 

Sets the maximum value of the SliderCell to aDouble. Returns self. 
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setMin Value: 


- setMinValue:(doubl &)aDouble 

Sets the minimum value of the SliderCell to aDouble. Returns self. 
setString Value: 

- setString Value: (const char *)aString 

Parses aString for a floating point value. If a floating point value can be parsed, then 
the SliderCell value is set and the knob position is updated to reflect the new value; 
otherwise, does nothing. Returns self 

startTrackingAt:inView: 

- (BOOL)startTrackingAt: (const NXPoint *)startPoint inViewicontrolView 
Begins a tracking session by moving the knob to startPoint. Always returns YES. 

stopTracking:at:inView:mouseIsUp: 

- stopTracking: (const NXPoint *)lastPoint 

at: (const NXPoint *)stopPoint 
in View icontrolView 
mouselsUp: (B OOL )flag 

Ends tracking by moving the knob to stopPoint. Returns self, 
string Value 

- (const char *)stringValue 

Returns a pointer to the value of the SliderCell, typecast as a string. 

trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent *)theEvent 

inRect: (const NXRect *)cellFrame 
ofView icontrolView 

Tracks the mouse until it goes up or until it goes outside the cellFrame. If cellFrame is 
NULL, then it tracks until the mouse goes up. If the SliderCell is continuous (see Cell’s 
setContinuous:), then the action will be continuously sent to the target as the mouse is 
tracked. If cellFrame isn’t the same cellFrame that was passed to the last 
drawSelf:inView:, then this method doesn’t track. Returns self. 

See also: - setContinous: 
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write: 

- write: (NXTypedStream *)stream 

Writes the receiving SliderCell to the typed stream stream and returns self. 
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Speaker 


INHERITS FROM Object 

DECLARED IN appkit/Speaker.h 

CLASS DESCRIPTION 

The Speaker class, with the Listener class, puts an Objective-C interface on Mach 
messaging. Mach messages are the way that applications (tasks) communicate with 
each other; they’re how remote procedure calls (RPCs) are implemented in the Mach 
operating system. 

A remote message is initiated by sending a Speaker instance the very same Objective-C 
message you want delivered to the remote application. The Speaker translates the 
message into the correct Mach message format and dispatches it to the receiving 
application’s port. A Listener in the receiving application reads the message from the 
port queue and translates in back into an Objective-C message, which it tries to delegate 
to another object. 

If the Speaker expects information back from the Listener, it will wait to receive a reply. 

Every application must have at least one Speaker and one Listener, if for no other 
reason but to communicate with the Workspace Manager. If you don’t create a Speaker 
in start-up code and register it as the application’s Speaker (with the setAppSpeaker: 
method), the Application object, when it receives a run message, will create one for 
you. 

For a general discussion of the Speaker-Listener interaction, see the Listener class. The 
descriptions here add Speaker-specific information, but don’t repeat any of the basic 
information presented there. In particular, the discussion here doesn’t explain the 
structure of remote messages or the distinction between input and output argument 
types. 


Sending Remote Messages 

Before sending a remote message, it’s necessary only to provide variables where output 
information—information returned to the Speaker by the receiving application—can be 
returned by reference, and to tell the Speaker which port to send the message to. 
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The example below shows a typical use of the Speaker class: 

int msgDelivered, fileOpened; 

id mySpeaker = [[Speaker alloc] init]; 

port_t thePort = NXPortFromName("SomeApp", NULL); 

/* Gets the public port for SomeApp */ 


if (thePort != PORT_NULL) { 

[mySpeaker setSendPort:thePort]; 

/* Sets the Speaker to send its 

* next message to SomeApp's port */ 
msgDelivered = [mySpeaker openFile:"/usr/foo" ok:&fileOpened]; 

/* Sends the message, here a message 

* to open the "/usr/foo" file. */ 

if (msgDelivered == 0) { 

if (fileOpened == YES) 


else 


} 

} 

[mySpeaker free]; /* Frees the Speaker 

* when it's no longer needed. */ 
port_deallocate(task_self(), thePort); 

/* Frees the application's 

* send rights to the port. */ 

The NXPortFromNameO function returns the port registered with the network name 
server under the name passed in its first argument. The second argument names the host 
machine; when it’s NULL, as in the example above, the local host is assumed. 

To find the port of the Workspace Manager, the constant 
NX_WORKSPACEREQUEST can be passed as the first argument to 
NXPortFromNameO. For example: 

port_t workspacePort; 

workspacePort = NXPortFromName(NX_WORKSPACEREQUEST, NULL); 

A Speaker can be dedicated to sending remote messages to a single application, in 
which case its destination port may need to be set only once. Or a single Speaker can 
be used to send messages to any number of applications, simply by resetting its port. 

It’s important to reset the destination port of the Speaker registered as the appSpeaker 
before each remote message. The Application Kit uses the appSpeaker to keep in 
contact with the Workspace Manager and so may reset its port behind your 
application’s back. 
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Return Values 


Each method that initiates a remote message returns an int that indicates whether the 
message was successfully transmitted or not. 

• If the message couldn’t be delivered to the receiving application, the return value 
will be one of the Mach error codes defined in the message.h header file in 
/usr/include/sys. 

• If the message was delivered, but the Listener didn’t recognize it or couldn’t 
delegate it to a responsible object, the return value is -1. 

• If the message was successfully delivered, recognized, and delegated, 0 is returned. 

A Mach error code is also returned if the Speaker times out while waiting for a return 
message. 


Copying Output Data 

The validity of all output arguments is guaranteed until the next remote message is sent. 
Then the memory allocated for a character string or a byte array will be freed 
automatically. If you want to save an output string or an array, you must copy it. When 
the amount of data is large, you can use the NXCopyOutputData() function to take 
advantage of the out-of-line data feature of Mach messaging. This function is passed 
the index of the output argument to be copied (the combination of a pointer and an 
integer for a byte array counts as a single argument) and returns a pointer to an area 
obtained through the vm_aIlocate() function. This pointer must be freed with 
vm_deallocate(), rather than free(). Note that the size of the area allocated is rounded 
up to the next page boundary, and so will be at least one page. Consequently, it is more 
efficient to ma!loc() and copy amounts up to about half the page size. 

Note: The application is responsible for deallocating all ports received when they’re 
no longer needed. 

INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Declared in Speaker 

port_t 

sendPort; 


port_t 

replyPort; 


int 

sendTimeout; 


int 

reply Timeout; 


id 

delegate; 
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sendPort 

The port to which the Speaker sends remote 
messages. 

replyPort 

The port where the Speaker receives return 
messages from the Listener of the remote 
application. 

sendTimeout 

How long the Speaker will wait for a remote 
message to be delivered at the port of the 
receiving application. 

reply Timeout 

How long the Speaker will wait, after a remote 
message is delivered, to receive a return message 
from the other application. 

delegate 

The Speaker’s delegate, which is generally 
unused. 

METHOD TYPES 


Initializing a new Speaker instance 

- init 

Freeing a Speaker 

- free 

Setting up a Speaker 

- setSendTimeout: 

- sendTimeout 

- setReplyTimeout: 

- replyTimeout 

Managing the ports 

- setSendPort: 

- sendPort 

- setReplyPort: 

- replyPort 

Standard remote methods 

- openFile:ok: 

- openTempFilerok: 

- launchProgram:ok: 

- powerOfflmandSave: 

- extendPo werOffB y: actual: 

- unmounting:ok: 
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Handing off an icon 

- iconEnteredrat: :icon Window :iconX:iconY: 

icon Width: iconHeight:pathList: 

- iconMovedTo:: 

- iconReleasedAt::ok: 

- iconExitedAt:: 

- registerWindowrtoPort: 

- unregisterWindow: 

Providing for program control 

- msgCalc: 

- msgCopyAsTypeiok: 

- msgCutAsType:ok: 

- msgDirectory:ok: 

- msgFile:ok: 

- msgPaste: 

- msgPosition:posType:ok: 

- msgPrint:ok: 

- msgQuit: 

- msgSelection:length:asType:ok: 

- msgSetPosition:posType:andSelect:ok: 

- msgVersion:ok: 

Getting file information 

- getFileIconFor:TIFF:TIFFLength:ok: 

- getFileInfoFor:app:type:ilk:ok: 

Sending remote messages 

-- performRemoteMethod: 

- performRemoteMethod:with:length: 

- selectorRPC.paramTypes:... 

- sendOpenFileMsg :ok: andDeactivateSelf: 

- sendOpenTempFileMsg :ok: andDeactivateSelf: 

Assigning a delegate 

- setDelegate: 

- delegate 

Archiving 

- read: 

- write: 


Application Kit Classes: Speaker 2-541 



INSTANCE METHODS 


delegate 

- delegate 

Returns the Speaker’s delegate. 

See also: - setDelegate: 

extendPowerOffBy:actual: 

- (int)extendPowerOffBy:(int)re#we.sTedMs' actual:(int *)actualMs 

Sends a remote message requesting more time before the power goes off or the user 
logs out. This message should be directed to the Workspace Manager. It’s sent in 
response to a powerOfflmandSave: message that doesn’t give the application enough 
time to prepare for the impending shutdown. 

requestedMs is how many additional milliseconds are needed, beyond the number 
given in the powerOfflmandSave: message. The actual number of additional 
milliseconds that are granted will be returned by reference in the integer referred to by 
actualMs. 

See also: - powerOfflmandSave: (Listener and Application), 

- app:powerOfflmandSave: (Application delegate) 

free 

- free 

Frees the memory occupied by the Speaker object, but does not deallocate its ports. 

getFileIconFor:TIFF:TIFFLength:ok: 

- (int)getFileIconFor:(char *)fullPath 

TIFF: (char **)tijfData 
TIFFLength:(int *)length 
ok:(int *)flag 

Sends a remote message requesting the icon for the fullPath file. This request should 
be directed to the Workspace Manager. 

fullPath is a string containing the complete path for a single file. tiffData is the address 
of a pointer that will be set to point to a byte array containing the icon image. The 
image is provided as TIFF (Tag Image File Format) data. The number of bytes in the 
tiffData array are returned by reference in the integer referred to by length. 
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flag is the address of an integer that will be set to YES if the Workspace Manager 
provides the icon, and to NO if it doesn’t. Here’s an example of a method the takes a 
pathname and returns an NXImage object containing the file’s icon: 

- workspacelmage:(char *)fullPath 

{ 

int ok, length; 
char *tiffData; 

NXStream *imageStream; 

id thelcon, mySpeaker = [NXApp appSpeaker]; 

[mySpeaker setSendPort: 

NXPortFromName(NX_WORKSPACEREQUEST,NULL)]; 

[mySpeaker getFilelconFor:fullPath TIFF:&tiffData 
TIFFLength:&length ok:&ok]; 

if (!ok) return nil; 

imageStream = NXOpenMemory(tiffData, length, NX_READONLY); 
if (!imageStream) return nil; 

thelcon = [[NXImage alloc] initFromStream:imageStream]; 

NXClose(imageStream); 

return thelcon; 

} 

You cannot use getFilelconFor:... from within an implementation of the 
iconEntered:at:... Listener method, as the Workspace will be blocked waiting for 
iconEntered:at:... to return. See the documentation for the iconEntered:at:...Listener 
method for information on copying the image of an icon that gets dragged into a 
window. 

See also: - getFileInfoFor:app:type:ilk:ok:, - iconEntered:at:... (Listener), 

- iconReleasedAt::ok: (Listener) 

getFilelnfoFor: app : ty pe: ilk: ok: 

- (int)getFileInfoFor:(char *)fullPath 

app:(char **)appName 
type:(char **)aType 
ilk:(int *)anllk 
ok:(int *)flag 

Sends a remote message asking for information about the fullPath file. This message 
should be sent to the Workspace Manager, which implements a method that can provide 
the requested information. 

appName is the address of a character pointer; the pointer will be set to point to the 
name of the application that the Workspace Manager would call upon to open the 
fullPath file. 
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aType is the address of a pointer that will be set to point to the file type. The type is 
typically the file name extension—“wn” for WriteNow files and “score” for music files 
in the ScoreFile language, for example. 

anllk is the address of an integer that will be set to one of the following constants: 


NX_ISODMOUNT 

fullPath is where a file system on an optical disk is 
mounted. 

NXJSSCSIMOUNT 

fullPath is where a file system on a hard disk is 
mounted. 

NXJSNETMOUNT 

fullPath is where a file system accessed over the 
network is mounted. 

NXJSDIRECTORY 

fullPath is a directory, but not one where a file system 
is mounted and not a file package. 

NXJSAPPLICATION 

fullPath is an executable file or a “.app” file package 
for an executable file. 

NX_ISFILE 

fullPath is a file or a file package (not one of the 
above). 


The last argument, flag, is the address of an integer that will be set to YES if the 
Workspace Manager provides the information requested by the three other arguments, 
and to NO if it doesn’t. 

To get the icon for fullPath, use getFi!eIconFor:TIFF:TIFFLength:ok:. 

See also: - getFileIconFor:TIFF:TIFFLength:ok: 

iconEntered:at::iconWindow:iconX:iconY:iconWidth:iconHeight:pathList: 

- (int)iconEntered : (int )windowN um 
at:(double)x 
:(double)y 

iconWindow:(in t)iconWindowNum 
iconX: (double)ico/?Y 
iconY:(double)zc<9«T 
iconWidth: (double)iconWidth 
iconHeight:(doubl e)iconHeight 
path List: (const char *)pathList 

Sends a remote message notifying another application that the user has dragged an icon 
into one of its windows. This notification is sent by the Workspace Manager; see the 
Listener class for information on how to receive 
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iconEntered:at::iconWindow:iconX:iconY:iconWidth:iconHeight:pathList: 

messages. 

See also: - registerWindowrtoPort: 
iconExitedAt:: 

- (int)iconExited At: (double)*: (double)^ 

Sends a remote message notifying the receiving application that the user dragged an 
icon out of one its registered windows. This notification is sent by the Workspace 
Manager; see the Listener class for information on receiving iconExitedAt:: messages. 

See also: - register Window:toPdrt:, iconExitedAt:: (Listener) 
iconMovedTo:: 

- (int)iconMovedTo: (double)* :(double)y 

Sends a remote message notifying another application that the user dragged an icon 
within one of its registered windows, to (*, y) in the screen coordinate system. This 
notification is sent by the Workspace Manager; see the Listener class for information 
on receiving iconMovedTo:: messages. 

See also: - registerWindow:toPort:, iconMovedTo:: (Listener) 

iconReleased At:: ok: 

- (int)iconReleased At: (double)* 

: (double )y 
ok:(int *)flag 

Sends a remote message notifying another application that the user has dragged an icon 
to one of its registered windows and released it there, at (*, y) in screen coordinates. 
This notification is sent by the Workspace Manager; see the Listener class for 
information on receiving iconReleasedAt::ok: messages. 

See also: - registerWindow:toPort:, iconReleasedAt::ok: (Listener) 


init 


- init 


Initializes the Speaker immediately after memory for it has been allocated by Object’s 
alloc or allocFromZone: methods. The new object’s sendTimeout and replyTimeout 
are both set to 30,000 milliseconds, its sendPort and replyPort are both PORT_NULL, 
and its delegate is nil. Returns self. 
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launchProgram:ok: 

- (int)launchProgram: (const char *)name ok:(int *)flag 

Sends a remote message requesting the receiver to launch the name application. This 
message is sent only to the Workspace Manager, the application responsible for 
executing programs that run in the workspace, name is the ordinary name of the 
application to be launched—for example, “Edit” or “Webster”, flag points to an integer 
that will be set to YES if the program is executed, and to NO if it’s not. 

The Application Kit initiates launchProgramrok: messages when it needs a running 
application to send another message. For example, the NXPortFromName() function 
uses this method to launch the application you name if it’s not already running. 

See also: - openFile:ok: (Application) 

msgCalc: 

- (int)msgCalc:(int *)flag 

Sends a remote message asking the receiving application to perform any calculations 
necessary to update its current window, flag points to an integer that will be set to YES 
if the calculations will be performed, and to NO if they won’t. 

msgCopyAsTypeiok: 

- (int)msgCopyAsType:(const char *)aType ok:(int *)flag 

Sends a remote message asking the receiving application to copy its current selection 
to the pasteboard as aType data, flag is the address of an integer that will be set to YES 
if the selection is copied, and to NO if it isn’t. 

msgCutAsType:ok: 

- (int)msgCutAsType: (const char *)aType ok:(int *)flag 

Sends a remote message requesting the receiving application to delete the current 
selection and put it in the pasteboard as aType data, flag points to an integer that will 
be set to YES if the request is carried out, and to NO if it isn’t. 

msgDirectory:ok: 

- (int)msgDirectory:(char *const *)fullPath ok:(int *)flag 

Sends a remote message asking the receiving application for its current directory. See 
the Listener class for information on the two arguments. 

See also: - msgDirectoryiok: (Listener) 
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msgFile:ok: 

- (int)msgFile:(char * const *)fullPath ok:(int *)jlag 

Sends a remote message asking the receiving application for its current document (the 
file displayed in the main window). See the Listener class for information on the two 
arguments. 

See also: - msgFileiok: (Listener) 

msgPaste: 

- (int)msgPaste:(int *)flag 

Sends a remote message asking the receiving application to replace its current selection 
with the contents of the pasteboard, just as if the user had chosen the Paste command 
in the Edit menu, flag is the address of an integer that will be set to YES if the receiving 
application will carry out the request, and to NO if it won’t. 

msgPosition:posType:ok: 

- (int)msgPosition:(char *const *)aString 

posType:(int *)anlnt 
ok:(int *)flag 

Sends a remote message asking the receiving application for information about its 
current selection. See the Listener class for information on the three arguments. 

See also: - msgPosition:posType:ok: (Listener) 


msgPrintiok: 

- (int)msgPrint:(const char *)fullPath ok:(int *)flag 

Sends a remote message asking the receiving application to print th efullPath file, then 
close it. flag points to an integer that will be set to YES if the file will be printed, and 
to NO if it won’t. 


msgQuit: 

- (int)msgQuit:(int *)flag 


Sends a remote message requesting the receiving application to quit, flag points to an 
integer that will be set to YES if the receiving application quits, and to NO if it doesn’t. 
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msgSe!ection:Iength:asType:ok: 

- (int)msgSeIection:(char *const *)bytes 

length :(int *)numBytes 
asType: (const char *)aType 
ok:(int *)flag 

Sends a remote message asking the receiving application to provide its current selection 
as aType data. See the Listener class for information on the four arguments. 

See also: - msgSe!ection:length:asType:ok: (Listener) 

msgSetPosition:posType:andSelect:ok: 

- (int)msgSetPosition: (const char *)aString 

posTy pe : (int )anlnt 
andSelect:(int).s/7<zg 
ok: (int *)flag 

Sends a remote message asking the receiving application to scroll its current document 
(the one displayed in the main window) so that the portion represented by aString is 
visible. See the Listener class for information on permitted argument values. 

See also: - msgSetPosition:posType:andSelect:ok: (Listener) 
msgVersiomok: 

- (int)msgVersion:(char *const *)aString ok:(int *)flag 

Sends a remote message asking the receiving application for its current version. See 
the Listener class for information on the arguments. 

See also: - msgVersion:ok: (Listener) 

openFileiok: 

- (int)openFile:(const char *)fullPath ok:(int *)flag 

Sends a remote message requesting another application to open the full Path file. Before 
the message is sent, the sending application is deactivated to allow the application that 
will open the file to become the active application. 

If the Workspace Manager is sent this message, it will find an appropriate application 
to open the file based on the file name extension. It will launch that application if 
necessary. 

flag is the address of an integer that the receiving application will set to YES if it opens 
the file, and to NO if it doesn’t. 

See also: - openFile:ok: (Application) 
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openTempFile:ok: 

- (int)openTempFile: (const char *)fullPath ok:(int *)flag 

Sends a remote message requesting another application to open a temporary file. The 
file is specified by an absolute pathname, fullPath. Before the message is sent, the 
sending application is deactivated to allow the application that will open the file to 
become the active application. 

Using this method instead of openFile:ok: lets the receiving application know that it 
should delete the file when it no longer needs it. 

See also: - openTempFileiok: (Application) 

performRemoteMethod: 

- (int)performRemoteMethod: (const char *)methodName 

Sends a remote message to perform the methodName method. The method must be one 
that takes no arguments. performRemoteMethod: is analogous to Object’s perform: 
method in that it permits you to send an arbitrary message. 

This method has the same return values as other methods that send remote messages: 
0 on success, a Mach error code if the message couldn’t be delivered, and -1 if it was 
delivered but wasn’t understood or couldn’t be delegated. 

See also: - selectorRPC:paramTypes: 

performRemoteMethod:with:length: 

- (int)performRemoteMethod: (const char *)methodName 

with: (const char *)data 
length: (int)numBy tes 

Sends a remote message to perform the methodName method and passes it the data byte 
array containing numBytes of data. This method is similar to Object’s perform:with: 
method in that it permits you to send an arbitrary message with one argument. 

performRemoteMethod:with:length: has the same return values as other methods 
that send remote messages: 0 on success, a Mach error code if the message couldn’t be 
delivered, and -1 if it was delivered but wasn’t understood or couldn’t be delegated. 

See also: - selector RPC: par amT y pes: 
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power Offln: andSave: 

- (int)powerOffTn:(int)m.v andSave :(int)aFlag 

Sends a remote message that the power is about to go off, or that the user is about to log 
out, in ms milliseconds. The Workspace Manager is the application that initiates this 
message, broadcasting it to all running applications. See the Listener and Application 
classes for information on how to respond to powerOffln:andSave: messages. 

See also: - powerOffln:andSave: (Listener and Application) 

read: 

- read:(NXTypedStream *)stream 

Reads the Speaker from the typed stream stream. The Speaker’s sendPort and 
reply Port instance variables will both be PORT_NULL. 

See also: - write 
registerWindow:toPort: 

- (int)registerWindow:(int)w/«dewiVMm toPort:(port_t )aPort 

Sends a remote message registering windowNum, so that the application will be notified 
when the user drags an icon over the window. This message should be sent to the 
Workspace Manager, which displays the file icons that users can drag to other windows. 
A window must be registered for it to accept icons dragged from the Workspace 
Manager and other applications. 

Once an window is registered, the Workspace Manager will dispatch messages to the 
application whenever the user drags an icon into, out of, or within the window. The 
Workspace Manager will also notify the application (with a iconReleasedAt::ok: 
message) when the user drops the icon in the window. The application can then either 
accept the icon, or reject it and have the Workspace Manager animate it back to its 
source window. 

windowNum is the global window number of the window that accepts icons. The global 
window number is the Window Server’s unique identifier for the window; it can be 
obtained from the Window object as follows: 

unsigned int global; 

NXConvertWinNumToGlobal([myWindow windowNum], &global); 


aPort is the port where the application wants to receive subsequent notification 
messages from the Workspace Manager. 

See also: - unregister Window:, - iconEntered:at:... (Listener), 

- dragFile:fromRect:slideBack:event: (View), 
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replyPort 

- (port_t)replyPort 

Returns the port where the Speaker expects to receive return messages. The Speaker 
caches this port as its replyPort instance variable. If this method returns 
PORT_NULL, the default, the Speaker will use the port returned by Application’s 
replyPort method. 

See also: - replyPort (Application), - setReplyPort: 

reply Timeout 

- (int)replyTimeout 

Returns how many milliseconds the Speaker will wait, after delivering a remote 
message to another application, for a return message to arrive back from the other 
application. 

See also: - setReplyTimeout: 

selectorRPC:paramTypes: 

- (int)selectorRPC: (const char *)methodName 

paramTypes:(char *)params, 


Sends a remote message to perform the methodName method with an arbitrary number 
of arguments. This is the general routine for sending remote messages and is used by 
most of the more specific Speaker methods. For example, a 
getFileInfoFor:app:type:ilk:ok: message could be sent as follows: 


int msgDelivered, infoProvided, thellk; 

char *theApp, *theExtension; 

msgDelivered = 

[mySpeaker selectorRPC:"getFilelnfoFor:app:type:ilk:ok:" 

paramTypes:"cCCII", "/usr/foo", 

StheApp, StheExtension, 

Sthellk, &infoProvided]; 

params is a character string, “cCCII” in the example above, that describes the 
arguments to the method. Each argument is represented by a single character that 
encodes its type. (A single character, “b” or “B”, represents the two Objective-C 
arguments of a byte array.) See the Listener class for an explanation of these codes. 

The actual arguments that will be passed to methodName are listed after params. 

This method has the same return values as other methods that send remote messages: 
0 on success, a Mach error code if the message couldn’t be delivered, and -1 if it was 
delivered but wasn’t understood or couldn’t be delegated. 


Application Kit Classes: Speaker 2-551 



sendOpenFileMsg: ok: and DeactivateSelf: 

- (int)sendOpenFileMsgt(const char *)fullPath 

ok:(int *)flag 

an&Y)tacti\ateSe\fi(BOOL)deactivateFirst 

Initiates an openFiletok: remote message, which could also be initiated by sending an 
openFile:ok: message directly to the Speaker. However, when a Speaker receives an 
openFiletok: message, it first deactivates the application in order to allow the receiving 
application to become active when it opens the file. 

In contrast, this way of sending an openFiletok: remote message gives the sending 
application control over whether it will deactivate before dispatching the message. If 
deactivateFirst is YES, this method works just like openFiletok:. If deactivateFirst is 
NO, the sending application will remain the active application. 

See also: -openFiletok: 

sendOpenTempFileMsgtoktandDeactivateSelf: 

- (int)sendOpenTempFileMsg: (const char *)fullPath 

ok:(int *)flag 

andDeactivateSe\f:(BOOL)deactivateFirst 

Initiates an openTempFiletok: remote message, which could also be initiated by 
sending an openTempFiletok: message directly to the Speaker. However, when a 
Speaker receives an openTempFiletok: message, it first deactivates the application in 
order to allow the receiving application to become active when it opens the file. 

In contrast, this way of sending an openTempFiletok: remote message gives the 
sending application control over whether it will deactivate before dispatching the 
message. If deactivateFirst is YES, this method works just like openTempFiletok:. If 
deactivateFirst is NO, the sending application will remain the active application. 

See also: - openTempFiletok: 

sendPort 

- (port_t)sendPort 

Returns the port the Speaker will send remote messages to. The Speaker caches this 
port as its sendPort instance variable. 

See also: - setSendPort: 
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sendTimeout 

- (int)sendTimeout 

Returns how many milliseconds the Speaker will wait for its remote message to be 
delivered to the port of the receiving application. The Speaker caches this value as its 
sendTimeout instance variable. If it’s 0, there’s no time limit. 

See also: - setSendTimeout: 

setDelegate: 

- setDelegat eianObject 

Makes anObject the Speaker’s delegate. The default delegate is nil. But before 
processing the first event, Application’s run method makes the Application object, 
NXApp, the delegate of the Speaker registered as the appSpeaker. If there is no 
appSpeaker, the run method creates one, registers it, and sets its delegate to be 
NXApp. 

Unlike a Listener, a Speaker doesn’t expect anything from its delegate. 

See also: - delegate, - setAppSpeaker: (Application) 

setReplyPort: 

- setReplyPort: (port_i)aPort 

Makes aPort the port where the Speaker receives return messages. If the Speaker sends 
a remote message with output arguments, it will supply the receiving application with 
send rights to this port, then wait for a return message containing the output data it 
requested. 

If aPort is PORTJNfULL, the Speaker will use a port supplied by the Application object 
in response to a reply Port message. Since return messages are read from the port as 
they arrive (synchronously), a number of different Speakers can share the same port. 

At start-up, before the run method gets the application’s first event, it sets the port of 
the Speaker registered as the appSpeaker to the port returned by Application’s 
replyPort method. 

See also: - replyPort, - replyPort (Application) 
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setReplyTimeout: 

- setReplyTimeout: (int)ms 

Sets, to ms milliseconds, how long the Speaker will wait to receive a reply from the 
application it sent a remote message. The Speaker expects a reply when the remote 
message it sends contains output arguments for information to be supplied by the 
receiving application. If ms is 0, there will be no time limit; the Speaker will wait until 
a return message is received or there’s a transmission error. The default is 30,000 
milliseconds. 

See also: - replyTimeout 

setSendPort: 

- setSendPort: (port_t)aPe>rf 

Makes aPort the port that the Speaker will send remote messages to. The default is 
PORT_NULL. A single Speaker can send remote messages to a variety of applications 
simply by setting a different port before each message. 

The NXPortFromNameO function can be used to find the public port of another 
application, as explained in the class description above. 

See also: - sendPort 

setSendTimeout: 

- setSendTimeout:(int)w5 

Sets, to ms milliseconds, how long the Speaker will persist in attempting to deliver a 
message to the port of the receiving application. If ms is 0, there will be no time limit; 
the Speaker will wait until the message is successfully delivered or there’s a 
transmission error. The default is 30,000 milliseconds. 

See also: - sendTimeout 
unmounting:ok: 

- (int)unmounting:(const char *)fullPath ok:(int *)flag 

Sends a remote message that a disk is about to be unmounted. When the user requests 
it to unmount a disk, the Workspace Manager sends unmounting:ok: messages to 
every running application. Other applications use the Listener version of the method 
to receive the Workspace Manager’s message. 

See also: - unmounting:ok: (Listener and Application) 


2-554 Chapter 2: Class Specifications 



unregisterWindow: 

- (int)unregisterWindow : (int )windowNum 

Sends a remote message cancelling the registration of windowNum as a window that 
accepts dragged icons. This message should be sent to the Workspace Manager. 
windowNum should have been previously registered with the registerWindowrtoPort: 
method. 

See also: - registerWindowrtoPort: 
write: 

- write:(NXTypedStream *)stream 

Writes the receiving Speaker to the typed stream stream. 

See also: - read 


CONSTANTS AND DEFINED TYPES 

/* File Information */ 

#define NX_ISFILE 0 

#define NX_ISDIRECTORY 1 

#define NX_ISAPPLICATION 2 

#define NX_ISODMOUNT 3 

#define NX_ISNETMOUNT 4 

#define NX ISSCSIMOUNT 5 
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INHERITS FROM 


View : Responder : Object 


DECLARED IN appkit/Text.h 

CLASS DESCRIPTION 

The Text class defines an object that manages text. Text objects are used by the 
Application Kit wherever text appears in interface objects: A Text object draws the title 
of a Window, the commands in a Menu, the title of a Button, and the items in an 
NXBrowser. Your application inherits these uses of the Text class when it incorporates 
any of these objects into its interface. It can also create Text objects for its own 
purposes. 

The Text class is unlike most other classes in the Application Kit in its complexity and 
range of features. One of its design goals is to provide a comprehensive set of 
text-handling features so that you’ll rarely need to create a subclass. A Text object can 
(among other things): 

• Control the color of its text and background. 

• Control the font and layout characteristics of its text. 

• Control whether text is editable. 

• Wrap text on a word or character basis. 

• Write text to, or read it from, an NXStream as either RTF or plain ASCII data. 

• Display graphic images within its text. 

• Communicate with other applications through the Services menu. 

• Let another object, the delegate, dynamically control its properties. 

• Let the user copy and paste text within and between applications. 

• Let the user copy and paste font and format information between Text objects. 

• Let the user check the spelling of words in its text. 

• Let the user control the format of paragraphs by manipulating a ruler. 

Interface Builder gives you access to Text objects in several different configurations, 
such as those found in the TextField, Form, and ScrollView objects in the Palettes 
window. These classes configure a Text object for a specific purpose. Additionally, all 
TextFields, Forms, Buttons within the same window—in short, all objects that access a 
Text object through associated Cells—share the same Text object, reducing the 
memory demands of an application. Thus, it’s generally best to use one of these classes 
whenever it meets your needs, rather than create Text objects yourself. If one of these 
classes doesn't provide enough flexibility for your purposes, use a Text object directly. 


Plain and Rich Text Objects 

When you create a Text object directly, by default it allows only one font, line height, 
text color, and paragraph format for the entire text. You can set the default font used 
by new Text instances by sending the Text class object a setDefaultFont: message. 
Once a Text object is created, you can alter its global settings using methods such as 
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setFont:, setLineHeight:, setTextGray:, and setAlignment:. For convenience, such 
a Text object will be called a plain Text object. 

To allow multiple values for these attributes, you must send the Text object a 
setMonoFont:NO message. A Text object that allows multiple fonts also allows 
multiple paragraph formats, line heights, and so on. Such a Text object can store the 
content and format of its text by writing RTF (Rich Text Format) data to the pasteboard 
or to a file. For convenience, such a Text object will be called a rich Text object. 

In a Text object, each sequence of characters having the same attributes is called a run. 
(See the NXRun structure at the end of this class specification for details.) A Text 
object in its default state has only one run for the entire text. A rich Text object can 
have multiple runs. Methods such as setSelFont:, setSelProp:to:, setSelGray:, and 
alignSelCenter: let you programmatically modify the attributes of the selected 
sequence of characters in a rich Text object. As discussed below, the user can set these 
attributes by using the Font panel and the ruler. 

Text objects are designed to work closely with various objects and services. Some of 
these (such as the delegate or an embedded graphic object) require a degree of 
programming on your part. Others (such as the Font panel, spelling checker, ruler, and 
Services menu) take no effort other than deciding whether the service should be 
enabled or disabled. The following sections discuss these interrelationships. 


Notifying the Text Object’s Delegate 

Many of a Text object’s actions can be controlled through an associated object, the Text 
object’s delegate. If it implements any of the following methods, the delegate receives 
the corresponding message at the appropriate time: 

textWillResize: 

textDidResize:oldBounds:invalid: 

textWillChange: 

textDidChange: 

textWillEnd: 

textDidEndrendChar: 

textDidGetKey s :isEmpty: 

textWillSetSelrtoFont: 

textWillConvert:fromFont:toFont: 

textWillWriteRichText:stream:forRun:atPosition:emitDefaultRichText: 

textWillReadRichText:stream:atPosition: 

textWillStartReadingRichText: 

textWillFinishReadingRichText: 

textWillWriterpaperSize: 

textDidRead:paperSize: 
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So, for example, if the delegate implements the textWillChange: method, it will 
receive notification upon the user’s first attempt to alter the text. Moreover, depending 
on the method’s return value, the delegate can either allow or prohibit changes to the 
text. (See the section titled “Methods Implemented by the Delegate” for more 
information.) The delegate can be any object you choose, and one delegate can be used 
to control multiple Text objects. 

Adding Graphics to the Text 

A rich Text object allows graphic objects to be embedded in the text. Each object is 
treated like a single character: The text’s line height and character placement are 
adjusted to accommodate the graphic “character.” 

In most cases, the graphic object is a subclass of Cell; however, the only requirement is 
that the embedded object be able to respond to these messages (see the section titled 
“Methods Implemented by an Embedded Graphic Object” for more information): 

highlight: in View: lit: 
drawSelf: in View: 
trackMouse: inRect:ofView: 
calcCellSize: 
readRichText: forView: 
writeRichText: forView: 

A graphic object can be placed in the text by sending the Text object a 
replaceSelWithCell: message. 

A Text object displays a graphic object in its text by sending the object a 
drawSelfrinView: message. To record the object to a file or to the pasteboard, the Text 
object sends it a writeRichTextrforView: message. The graphic object must then write 
an RTF control word along with any data (such as the path of a TIFF file containing its 
image data) it might need to recreate its image. To reestablish the text containing the 
graphic image from RTF data, a Text object must know which class to associate with 
particular RTF control words. You associate a control word with a class object by 
sending the Text class object a registerDirectiveiforClass: message. Thereafter, 
whenever a Text object finds the registered control word in RTF data being read from 
a file or the pasteboard, it will create a new instance of the class and send the object a 
readRichText:forView: message. 
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Cooperating with Other Objects and Services 

Text objects are designed to work with the Application Kit’s font conversion system. 
By default, a Text object keeps the Font panel updated with the font of the current 
selection. It also changes the font of the selection (for a rich Text object) or of the entire 
text (for a default Text object) to reflect the user's choices in the Font panel or menu. 
To disconnect a Text object from this service, send it a setFontPanelEnabledrNO 
message. 

If a Text object is a subview of a ScrollView, it can cooperate with the ScrollView to 
display and update a ruler that displays formatting information. The ScrollView retiles 
its subviews to make room for the ruler, and the Text object updates the ruler with the 
format information of the paragraph containing the selection. The toggleRuler: 
method controls the display of this ruler. Users can modify paragraph formats by 
manipulating the components of the ruler. 

By means of the Services menu, a Text object can make use of facilities outside the 
scope of its own application. By default, a Text object registers with the services 
system that it can send and receive RTF and plain ASCII data. If the application 
containing the Text object has a Services menu, a menu item is added for each service 
provider that can accept or return these formats. To prevent Text objects from 
registering for services, send the Text class object an 

excludeFromServicesMenuiYES message before any Text objects are created. 

INSTANCE VARIABLES 


Inherited from Object 

Class 

isa; 

Inherited from Responder 

id 

nextResponder; 

Inherited from View 

NXRect 

frame; 


NXRect 

bounds; 


id 

superview; 


id 

subviews; 


id 

window; 


struct_vFlags 

vFlags; 
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Declared in Text 


const NXFSM 

*breakTable; 

const NXFSM 

*clickTable; 

const unsigned char 

*preSelSmartTable; 

const unsigned char 

*postSelSmartTable; 

const unsigned char 

*charCategoryTable; 

char 

delegateMethods; 

NXCharFilterFunc 

charFilterFunc; 

NXTextFilterFunc 

textFilterFunc; 

NXTextFunc 

scanFunc; 

NXTextFunc 

drawFunc; 

id 

delegate; 

int 

tag; • 

DPSTimedEntry 

cursorTE; 

NXTextBlock 

*firstTextBlock; 

NXTextBlock 

*lastTextBlock; 

NXRunArray 

*theRuns; 

NXRun 

typingRun; 

NXBreakArray 

*theBreaks; 

int 

growLine; 

int 

textLength; 

NXCoord 

maxY; 

NXCoord 

maxX; 

NXRect 

bodyRect; 

NXCoord 

borderWidth; 

char 

clickCount; 

NXSelPt 

spO; 

NXSelPt 

spN; 

NXSelPt 

anchorL; 

NXSelPt 

anchorR; 

float 

backgroundGray; 

float 

textGray; 

float 

selectionGray; 

NXSize 

maxSize; 

NXSize 

minSize; 

struct _tFlags { 


unsigned int 

changeState: 1; 

unsigned int 

charWraprl; 

unsigned int 

haveDown:l; 

unsigned int 

anchorlsOrl; 

unsigned int 

horizResizablerl; 

unsigned int 

vertResizablerl; 

unsigned int 

overstrikeDiacriti 

unsigned int 

monoFontrl; 

unsigned int 

disableFontPanel: 

unsigned int 

inClipView:l; 

} 

tFlags; 

NXStream 

*textStream; 
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breakTable 

clickTable 

preSelSmartTable 

postSelSmartTable 

charCategory Table 

delegateMethods 

charFilterFunc 

textFilterFunc 

scanFunc 

drawFunc 

delegate 

tag 

cursorTE 

firstTextBlock 

lastTextBlock 

theRuns 

typingRun 


A pointer to the finite-state machine table that 
specifies word and line breaks. 

A pointer to the finite-state machine table that defines 
word boundaries for double-click selection. 

A pointer to the table that specifies which characters 
on the left end of a selection are treated as equivalent 
to a space. 

A pointer to the table that specifies which characters 
at the right end of a selection are treated as equivalent 
to a space. 

A pointer to the table that maps ASCII characters to 
character classes. Entries are premultiplied by the 
size of a finite-state machine table entry. 

A record of the notification methods that the delegate 
implements. 

The function that checks each character as it’s typed 
into the text. 

The function that checks the text that’s being added to 
the Text object. 

The function that calculates the line of text. 

The function that draws the line of text. 

The object that’s notified when the Text object is 
modified. 

The integer that the delegate uses to identify the Text 
object. 

The timed-entry number returned by 
DPS AddTimedEntry (). 

A pointer to the first record in a linked list of text 
blocks. 

A pointer to the last record in a linked list of text 
blocks. 

A pointer to the array of format runs. By default, 
theRuns points to a single run of the default font. 

The format run to use for the next characters entered. 
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theBreaks 

A pointer to the array of line breaks. 

growLine 

The line containing the end of the growing selection. 

textLength 

The number of characters in the Text object. 

maxY 

The bottom of the last line of text. maxY is measured 
relative to the origin of the bodyRect. 

maxX 

The widest line of text. maxX is accurate only after 
the calcLine method is applied. 

bodyRect 

The rectangle the Text object draws text in. 

borderWidth 

Reserved for future use. 

clickCount 

The number of clicks that created the selection. 

spO 

The starting position of the selection. 

spN 

The ending position of the selection. 

anchorL 

The left anchor position. 

anchorR 

The right anchor position. 

backgroundGray 

The background gray value of the text. 

textGray 

The gray value of the text. 

selectionGray 

The gray value of the selection. 

maxSize 

The maximum size of the frame rectangle. 

minSize 

The minimum size of the frame rectangle. 

tFlags .changeState 

True if any changes have been made to the text since 
the Text object became the first responder. 

tFlags.charWrap 

True if the Text object wraps words whose length 
exceeds the line length on a character basis. False if 
such words are truncated at the end of the line. 

tFlags.haveDown 

True if the left mouse button (or either button if their 
functions haven’t been differentiated) is down. 

tFlags. anchorlsO 

True if the anchor’s position is at spO. 

tFlags.horizResizable 

True if the Text object’s width can grow or shrink. 


Application Kit Classes: Text 2-563 



tFlags. vertResizable 

True if the Text object’s height can grow or shrink. 

tFlags .overstrikeDiacriticals 

Reserved for future use. 

tFlags.monoFont 

True if the Text object uses one font for all its text. 

tFlags .disableFontPanel 

True if the Text object doesn’t update the Font panel 
automatically. 

tFlags.inClipView 

True if the Text object is the subview of a Clip View. 

textStream 

The stream for reading and writing text. 

METHOD TYPES 


Initializing the class object 

+ setDefaultFont: 

+ getDefaultFont 
+ excludeFromServicesMenu: 

+ registerDirectiveiforClass: 

+ initialize 

Initializing a new Text object 

- initFrame: 

- initFrame:text:alignment: 

Freeing Text object 

- free 

Modifying the frame rectangle 

- setMaxSize: 

- getMaxSize: 

- setMinSize: 

- getMinSize: 

- set VertResizable: 

- isVertResizable 

- setHorizResizable: 

- isHorizResizable 

- sizeTo:: 

- sizeToFit 

- resizeText:: 

- moveTo:: 
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Laying out the text - setMarginLeft:right:top:bottom: 

-getMarginLeft:right:top:bottom: 

- getMinWidth:minHeight:maxWidth:maxHeight: 

- setAlignment: 

- alignment 

- alignSelLeft: 

- alignSelCenter: 

- alignSelRight: 

- setSelProp:to: 

- changeTabStopAt:to: 

- calcLine 

- setCharWrap: 

- charWrap 

- setNoWrap 

- setParaStyle: 

- defaultParaStyle 

- calcParagraphStyle:: 

- setLineHeight: 

- lineHeight 

- setDescentLine: 

- descentLine 

Reporting line and position - lineFromPosition: 

- positionFromLine: 

Setting, reading, and writing the text 

- setText: 

- readText: 

- startReadingRichText 

- readRichText: 

- readRichTextiatPosition: 

- finishReadingRichText 

- writeText: 

- writeRichText: 

- writeRichText:from:to: 

- writeRichText:forRun:atPosition: 

emitDefaultRichText: 

- stream 

- firstTextBlock 

- getParagraph: start: end :rect: 

- getSubstring:start:length: 

- byteLength 

- textLength 

Setting editability - setEditable: 

- isEditable 
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Editing the text 


Managing the selection 


Setting the font 


Checking spelling 


- copy: 

- copyFont: 

- copyRuler: 

- paste: 

- pasteFont: 

- pasteRuler: 

- cut: 

- delete: 

- clear: 

- selectAll: 

- selectText: 

- subscript: 

- superscript: 

- unscript: 

- underline: 

- showCaret 

- hideCaret 

- setSelectable: 

- isSelectable 

- selectError 

- selectNull 

- setSel:: 

- getSel:: 

- replaceSel: 

- replaceSel'.length: 

- replaceSel:length:runs: 

- replaceSelWithRichText: 

- scrollSelToVisible 

- setMonoFont: 

- isMonoFont 

- setFontPanelEnabled: 

- isFontPanelEnabled 

- changeFont: 

- setFont: 

- font 

- setFont:paraStyle: 

- setSelFont: 

- setSelFontFamily: 

- setSelFontSize: 

- setSelFontStyle: 

- setSelFont:paraStyle: 

- checkspelling: 

- showGuessPanel: 


Managing the ruler - toggleRuler: 

- isRulerVisible 
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Modifying graphic attributes 

- setBackgroundGray: 

- backgroundGray 

- setBackgroundColor: 

- backgroundColor 

- setSelGray: 

- selGray 

- setSelColor: 

- setTextGray: 

- textGray 

- setTextColor: 

- textColor 

Reusing a Text object 

- renewFont:text:frame:tag: 
-renewFont:size:style:text:frame:tag: 

- renewRuns:text:frame:tag: 

- windowChanged: 

Displaying 

- drawSelf:: 

- setRetainedWhileDrawing: 

- isRetainedWhileDrawing 

Assigning a tag 

- setTag: 

-tag 

Handling event messages 

- acceptsFirstResponder 

- becomeFirstResponder 

- resignFirstResponder 

- becomeKey Window 

- resignKey Window 

- mouseDown: 

- keyDown: 

- moveCaret: 

Displaying graphics within the text 

+ registerDirectiverforClass: 

- replaceSelWithCell: 

- replaceSelWithView: 

- setLocationrofCell: 

- getLocation:ofCell: 

- getLocationrofView: 

Using the Services menu 

+ excludeFromServicesMenu: 

- validRequestorForSendType: 

andRetumType: 

- readSelectionFromPasteboard: 

- writeSelectionToPasteboard:types: 
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Setting tables and functions - setCharFilter: 

- charFilter 

- setTextFilter: 

- textFilter 

- setBreakTable: 

- breakTable 

- setPreSelSmartTable: 

- preSelSmartTable 

- setPostSelSmartTable: 

- postSelSmartTable 

- setCharCategoryTable: 

- charCategoryTable 

- setClickTable: 

- clickTable 

- setScanFunc: 

- scanFunc 

- setDrawFunc: 

- drawFunc 


Printing 


- adjustPageHeightNew:top:bottom:limit: 


Archiving 


- read: 

- write: 


Assigning a delegate - setDelegate: 

- delegate 


CLASS METHODS 

excludeFr omSer vicesMenu: 

+ excludeF romServicesMenu : (BOOL)//<ag 

Controls whether Text objects will communicate with interapplication services through 
the Services menu. By default, as each new Text instance is initialized, it registers with 
the Application object that it’s capable of sending and receiving the pasteboard types 
identified by NXAsciiPboardType and NXRTFPboardType. If you want to prevent 
Text objects in your application from registering for services that can receive and send 
these types, send the Text class object an excludeFromServicesMenu: YES message. 
If, for example, your application displays text but doesn’t have editable text fields, you 
might use this method. 

Send an excludeFromServicesMenu: message early in the execution of your 
application, either before sending the Application object a run message or in the 
Application delegate’s appWilllnit: method. Returns self. 

See also: - validRequestorForSendTyperandReturnType:, 

- registerServicesMenuSendTypesrandReturnTypes: (Application) 
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getDefaultFont 
+ getDefaultFont 

Returns the Font object that corresponds to the Text object’s default. Unless you’ve 
changed the default font by sending a setDefaultFont: message, or taken advantage of 
the NXFont parameter using defaults, getDefaultFont returns a Font object for a 
12-point Helvetica font with a flipped font matrix. 

See also: + setDefaultFont:, - setFont: 

initialize 
+ initialize 

Initializes the class object. The initialize message is sent for you before the class object 
receives any other message; you never send an initialize message directly. Returns self. 

See also: + initialize (Object) 

registerDirective:forClass: 

+ register Directive: (const char *)directive forClass:c/<m 

Creates an association in the Text class object between the RTF control word directive 
and class, a class object. Thereafter, when a Text instance encounters directive while 
reading a stream of RTF text, it creates a new class instance. The new instance is sent 
a readRichText:forView: message to let it read its image data from the RTF text. 
Conversely, when a Text object is writing RTF data to a stream and encounters an object 
of the class class, the Text object sends the object a writeRichText-.forView: message 
to let it record its representation in the RTF text. Thus, this method is instrumental in 
enabling a Text object to read, display, and write an image within a text stream. 

An object of the class class must implement these methods: 

highlight:inView:lit: 
drawSelf :in View: 
trackMouse:inRect:ofView: 
calcCellSize: 
readRichText:forView: 
writeRichText: for View: 

See the section titled “Methods Implemented by an Embedded Graphic Object” for 
more information on these methods. 

Returns nil if directive or class has already been registered; otherwise, returns self. 
See also: - replaceSelWithCell: 
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setDefaultFont: 


+ seiDefaultFontianObject 

Sets the default font for the Text class object. The argument passed to this method is 
the id of the Font object for the desired font. Since a Text object uses a flipped 
coordinate system, make sure the Font object you specify uses a matrix that flips the 
y-axis of the characters. Returns anObject. 

See also: + getDefaultFont, - setLineHeight:, + newFontrsize: (Font) 


INSTANCE METHODS 

acceptsFirstResponder 

- (BOOL)acceptsFirstResponder 

Assuming the text is selectable, returns YES to let the Text object become the first 
responder; otherwise, returns NO. acceptsFirstResponder messages are sent for you; 
you never send them yourself. 

See also: - setSelectable:, - setDelegate:, - resignFirstResponder 

adjustPageHeightNew:top:bottom:limit: 

- adjustPageHeightNew: (float *)newBottom 

top:(float)o/d7bp 
bottom: (float )oldBottom 
limit: (fioat)bottomLimit 

During automatic pagination, this method is performed to help lay a grid of pages over 
the top-level view being printed. newBottom is passed in undefined and must be set by 
this method. oldTop and oldBottom are the current values for the horizontal strip being 
created. bottomLimit is the topmost value newBottom can be set to. If this limit is 
broken, the new value is ignored. By default, this method tries to prevent the view from 
being cut in two. All parameters are in the view’s own coordinate system. Returns self. 
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alignment 

- (int)alignment 

Returns a value indicating the default alignment of the text. The returned value is equal 
to one of these constants: 

Constant 

NX_LEFTALIGNED 
NX_RIGHTALIGNED 
NX_CENTERED 

NX_JU STIFIED 

See also: - setAlignment: 

alignSelCenter: 

- alignSelCenter: sender 

Sets the paragraph style of one or more paragraphs so that text is centered between the 
left and right margins. For a plain Text object, all paragraphs are affected. For a rich 
Text object, only those paragraphs marked by the selection are affected. The sending 
object passes its id as part of the alignSelCenter: message. The text is rewrapped and 
redrawn. Returns self. 

See also: - alignSelLeft:, - alignSelRight:, - setSelProp:to:, - setMonoFont: 

alignSelLeft: 

- alignSelLeft : sender 

Sets the paragraph style of one or more paragraphs so that text is aligned to the left 
margin. For a plain Text object, all paragraphs are affected. For a rich Text object, only 
those paragraphs marked by the selection are affected. The sending object passes its id 
as part of the alignSelLeft: message. The text is rewrapped and redrawn. Returns self. 

See also: - alignSelCenter:, - alignSelRight:, - setSelProp:to:, - setMonoFont: 


Alignment 

Flush to left edge of the bodyRect. 

Flush to right edge of the bodyRect. 

Each line centered between left and right edges of the 

bodyRect. 

Flush to left and right edges of the bodyRect; 
justified. Not yet implemented. 
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alignSelRight: 

- alignSeIRight:.serafer 

Sets the paragraph style of one or more paragraphs so that text is aligned to the right 
margin. For a plain Text object, all paragraphs are affected. For a rich Text object, only 
those paragraphs marked by the selection are affected. The sending object passes its id 
as part of the alignSelRight: message. The text is rewrapped and redrawn. Returns 
self. 

See also: - alignSelCenter:, - alignSelLeft:, - setSelProp:to:, - setMonoFont: 

backgroundColor 

- (NXColor)backgroundColor 

Returns the background color of the text. 

See also: - setBackgroundGray:, - backgroundGray:, - setBackgroundColor:, 

- setTextGray:, - textGray, - setTextColor:, - textCoIor, - setSelGray:, 

- selGray, - setSelColor: 

backgroundGray 

- (float)backgroundGray 

Returns the gray value of the text’s background. 

See also: - setBackgroundGray:, - setBackgroundColor:, - backgroundColor, 
-setTextGray:, - textGray, - setTextColor:, - textCoIor, - setSelGray:, - selGray, 

- setSelColor: 

becomeFirstResponder 

- becomeFirstResponder 

Lets the Text object know that it’s becoming the first responder. By default, the Text 
object always accepts becoming first responder. becomeFirstResponder messages are 
sent for you; you never send them yourself. Returns self. 

See also: - setDelegate:, -acceptsFirstResponder, - selectError 

becomeKeyWindow 

- becomeKeyWindow 

Activates the caret if it exists. becomeKeyWindow messages are sent by an 
application’s Window object, which, upon receiving a mouse-down event, sends a 
becomeKeyWindow message to the first responder. You should never directly send 
this message to a Text object. Returns self. 

See also: - showCaret, - hideCaret, - becomeKeyWindow (Window) 
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breakTable 


- (const NXFSM *)breakTable 

Returns a pointer to the break table, the finite-state machine table that the Text object 
uses to determine word boundaries. 

See also: - setBreakTable: 


byteLength 

- (int)byteLength 

Returns the number of bytes used by the characters in the receiving Text object. The 
number doesn’t include the null terminator (‘\0’) that getSubstring:start:length: 
returns if you ask for all the text in a Text object. 

In a standard Text object, the number of bytes is equal to the number of characters. 
Subclasses of Text that use more than one byte per character should override this 
method to return an accurate count of the number of bytes used to store the text. 

See also: - textLength, - getSubstring:start:length: 


calcLine 

- (int)calcLine 


Calculates the array of line breaks for the text. The text will then be redrawn if 
autodisplay is set. 


This message should be sent after the Text object’s frame is changed. These methods 
send a calcLine message as part of their implementation: 


- initFrame: text: alignment: 

- read: 

- renewFont:text:frame:tag: 

- renewRuns:text:frame:tag: 

- setFont:paraStyle: 


- readText: 

- renewFont:size:style:text:frame:tag: 

- setFont: 

- setParaStyle: 

- setText: 


In addition, if a vertically resizable Text object is the document view of a Scroll View, 
and the ScrollView is resized, the Text object receives a calcLine message. Has no 
significant return value. 

See also: - readText:, - renewRuns:text:frame:tag: 
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calcParagraphStyle:: 

- (void *)calcParagraphStyle:/oftr/d :(int )alignment 

Recalculates the default paragraph style given the Font’s fontld and alignment. The 
Text object sends this message for you after its font has been changed; you will rarely 
need to send a calcParagraphStyle:: message directly. Returns a pointer to an 
NXTextStyle structure that describes the default style. 

See also: - defaultParaStyle 

changeFont: 

- changeFontise^dcr 

Changes the font of the selection for a rich Text object. It changes the font for the entire 
Text object for a plain Text object, sender must respond to the convertFont: message. 

If the Text object’s delegate implements the method, it receives a 
textWillConvert:fromFont:toFont: notification message for each text run that’s about 
to be converted. 

See also: - setFontPanelEnabled: 
changeTabStopAt:to: 

- changeTabStop At: (NXCoord)o/dX to: (NXCoord)rcewX 

Moves the tab stop from the receiving Text object’s x coordinate oldX to the coordinate 
newX. For a plain Text object, all paragraphs are affected. For a rich Text object, only 
those paragraphs marked by the selection are affected. The text is rewrapped and 
redrawn. Returns self. 

See also: - setMonoFont:, - setSelProp:to: 
charCategoryTable 

- (const unsigned char *)charCategoryTable 

Returns a pointer to the character category table, the table that maps ASCII characters 
to character categories. 

See also: - setCharCategoryTable: 
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charFilter 

- (NXCharFilterFunc)charFilter 

Returns the character filter function, the function that analyzes each character the user 
enters. By default, this function is NXEditorFilter(). 

See also: - setCharFilter: 

charWrap 

- (BOOL)charWrap 

Returns charWrap, a flag indicating how words whose length exceeds the line length 
should be treated. If YES, long words are wrapped on a character basis. If NO, long 
words are truncated at the boundary of the bodyRect. 

See also: - setCharWrap: 

checkSpelling: 

- checkSpellingisender 

Searches for a misspelled word in the text of the receiving Text object. The search starts 
at the current selection and continues until it reaches a word suspected of being 
misspelled or the end of the text. If a word isn’t recognized by the spelling server or 
listed in the user’s local dictionary in ~/.NeXT/LocalDictionary, it’s highlighted. A 
showGuessPanel: message will then display the Guess panel and allow the user to 
make a correction or add the word to the local dictionary. Returns self. 

See also: - showGuessPanel: 

clear: 

- clear ‘.sender 

Provided for backward compatibility. Use the delete: method instead. 

See also: - delete: 

clickTable 

- (const NXFSM *)clickTable 

Returns a pointer to the click table, the finite-state machine table that defines word 
boundaries for double-click selection. 

See also: - setClickTable: 
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copy: 

- copy '.sender 

Copies the selected text from the Text object to the selection pasteboard. The selection 
remains unchanged. The pasteboard receives the text and its corresponding run 
information. The pasteboard types used are NXAsciiPboardType and 
NXRTFPboardTy pe. 

The sender passes its id as part of the copy: message. Returns self. 

See also: - cut:, - paste:, - delete:, - copyFont:, - pasteFont:, - copyRuler:, 

- pasteRuler: 

copyFont: 

- copyFon tisender 

Copies font information for the selected text to the font pasteboard. If the selection 
spans more than one font, the information copied is that of the first font in the selection. 
The selection remains unchanged. The pasteboard type used is NXFontPboardType. 

The sender passes its id as the argument of the copyFont: message. Returns self. 

See also: - pasteFont:, - copyRuler:, - pasteRuler:, - copy:, - cut:, - paste:, 

- delete: 

copyRuler: 

- copyRuler '.sender 

Copies ruler information for the paragraph containing the selection to the ruler 
pasteboard. The selection expands to paragraph boundaries. 

The ruler controls a paragraph’s text alignment, tab settings, and indentation. If the 
selection spans more than one paragraph, the information copied is that of the first 
paragraph in the selection. The pasteboard type used is NXRulerPboardType. 

Once copied to the pasteboard, ruler information can be pasted into another object or 
application that’s able to paste RTF data into its document. 

The sender passes its id as the argument of the copyRuler: message. Returns self. 

See also: - pasteRuler:, - copyFont:, - pasteFont:, - copy:, - cut:, - paste:, 

- delete: 
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cut: 


- cut: sender 

Copies the selected text to the pasteboard and then deletes it from the Text object. The 
pasteboard receives the text and its corresponding font information. 

If the Text object’s delegate implements the method, it receives a 
textDidGetKeys:isEmpty: message immediately after the cut operation. If this is the 
first change since the Text object became the first responder (and the delegate 
implements the method), a textDidChange: message is also sent to the delegate. 

The sender passes its id as part of the cut: message. Returns self. 

See also: - copy:, - paste:, - delete:, - textDidGetKeys:isEmpty:, 

- textDidChange: 

defaultParaStyle 

- (void *)defaultParaStyle 

Returns by reference the default paragraph style for the text. The pointer that’s returned 
refers to an NXTextStyle structure. The fields of this structure contain default 
paragraph indentation, alignment, line height, descent line, and tab information. The 
Text object’s default values for these attributes can be altered using methods such as 

setParaStyle:, setAlignment:, setLineHeight:, and setDescentLine:. 

See also: - setParaStyle:, - setAlignment:, - setLineHeight:, - setDescentLine: 

delegate 

- delegate 

Returns the Text object’s delegate. 

See also: - setDelegate: 
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delete: 


- delete '.sender 

Deletes the selection without adding it to the pasteboard. The sender passes its id as 
part of the delete: message. 

If the Text object’s delegate implements the method, it receives a 
textDidGetKeys:isEmpty: message immediately after the delete operation. If this is 
the first change since the Text object became the first responder (and the delegate 
implements the method), a textDidChange: message is also sent to the delegate. 

The delete: method replaces clear:. Returns self. 

See also: - cut:, - copy:, - paste:, - textDidGetKeysrisEmpty:, - textDidChange: 

descentLine 

- (NXCoord)descentLine 

Returns the default descent line for the Text object. The descent line is the distance 
from the bottom of a line of text to the base line of the text. 

See also: - setDescentLine: 

drawFunc 

- (NXTextFunc)drawFunc 

Returns the draw function, the function that’s called to draw each line of text. 
NXDrawALine() is the default draw function. 

See also: - setDrawFunc:, - setScanFunc: 
drawSelf:: 

- drawSelf: (const NXRect *)rects :(mt)rectCount 

Draws a Text object. You never send a drawSelf:: message directly, although you may 
want to override this method to change the way a Text object draws itself. Returns self. 

See also: - drawSelf:: (View) 
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finishReadingRichText 

- finishReadingRichText 

Notifies the Text object that it has finished reading RTF data. The Text object responds 
by sending its delegate a textWillFinishReadingRichText: message, assuming there 
is a delegate and it responds to this message. The delegate can then perform any 
required cleanup. Alternatively, a subclass of Text could put these cleanup routines in 
its own implementation of this method. Returns self. 

firstTextBlock 

- (NXTextBlock *)firstTextBIock 

Returns a pointer to the first text block. You can traverse this head of the linked list of 
text blocks to read the contents of the Text object. In most cases, however, it’s better to 
use the getSubstring:start:length: method to get a substring of the text or the stream 
method to get read-only access to the entire contents of the Text object. 

See also: - getSubstring:start:length:, - stream 

font 

- font 

Returns the Font object for a plain Text object. For rich Text objects, the Font object 
for the first text run is returned. 

See also: - setFont: 

free 

- free 

Releases the storage for a Text object. 

See also: - free (View) 

getLocation:ofCell: 

- getLocation:(NXPoint *)origin ofCel hcell 

Places the x and y coordinates of cell in the NXPoint structure specified by origin. The 
coordinates are in the Text object’s coordinate system, cell is a Cell object that’s 
displayed as part of the text. 

Returns nil if the Cell object isn’t part of the text; otherwise, returns self. 

See also: - replaceSelWithCell:, - setLocation:ofCell:, - getLocatiomofView:, 

- calcCellSize: (Cell) 
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getLocationrofView: 

- getLocation:(NXPoint *)origin ofView:vz>w 
Unimplemented. 

getMarginLeft: right: top: bottom: 

- getMarginLeft: (NXCoord *)leftMargin 

right :(NXCoord *)rightMargin 
top: (NXCoord *)topMargin 
bottom: (NXCoord *)bottomMargin 

Calculates the dimensions of the Text object’s margins and returns by reference these 
values in its four arguments. Returns self. 

See also: - setMarginLeft:right:top:bottom: 
getMaxSize: 

- getMaxSize:(NXSize *)theSize 

Copies the maximum size of the Text object into the structure referred to by the Size. 
Returns self. 

See also: - setMaxSize:, - getMinSize: 
getMinSize: 

- getMinSize :(NXSize *)theSize 

Copies the minimum size of the Text object into the structure referred to by theSize. 
Returns self. 

See also: - setMinSize:, - getMaxSize: 

getMinWidth:minHeight:maxWidth:maxHeight: 

- getMinWidth: (NXCoord *)width 

minHeight:(NXCoord *)height 
max Width: (NXCoord )widthMax 
maxHeight:(NXCoord )heightMax 

Calculates the minimum width and height needed to contain the text. Given a 
maximum width and height ( widthMax and heightMax), this method copies the 
minimum width and height to the addresses pointed to by the width and height 
arguments. This method doesn’t rewrap the text. To get the absolute minimum 
dimensions of the text, send a getMinWidth:minHeight:maxWidth:maxHeight: 
message only after sending a calcLine message. 
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The values derived by this method are accurate only if the Text object hasn’t been 
scaled. Returns self. 

See also: - sizeToFit 

getParagraph:start:end:rect: 

- getParagraph:(int )prNumber 

start: (int *)startPos 
end:(int *)endPos 
rect:(NXRect *)paragraphRect 

Copies the positions of the first and last characters of the specified paragraph to the 
addresses startPos and endPos. It also copies the paragraph’s bounding rectangle into 
the structure referred to by paragraphRect. A paragraph ends in a Return character; the 
first paragraph is paragraph 0, the second is paragraph 1, and so on. Returns self. 

See also: - getSubstring:start:length:, - firstTextBlock 
getSel:: 

- getSel:(NXSelPt *)start :(NXSelPt *)end 

Copies the starting and ending character positions of the selection into the addresses 
referred to by start and end. start points to the beginning of the selection; end points 
to the end of the selection. Returns self. 

See also: -setSel:: 

getSubstring:start:length: 

- (int)getSubstring:(char *)buf 

start: (mi) startPos 
length: (int )numChars 

Copies a substring of the text to a specified memory location. The substring is specified 
by startPos and numChars. startPos is the position of the first character of the 
substring; numChars is the number of characters to be copied, buf is the starting 
address of the memory location for the substring. getSubstring:start:length: returns 
the number of characters actually copied. This number may be less than numChars if 
the last character position is less than startPos + numChars. Returns -1 if startPos is 
beyond the end of the text. 

getSubstring:start:length: appends a null terminator (‘\0’) to the substring only if the 
requested substring includes the end of the Text object’s text. 

See also: - textLength, - getSel:: 
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hideCaret 

- hideCaret 

Removes the caret from the text. The Text object sends itself hideCaret messages 
whenever the display of the caret would be inappropriate; you rarely need to send a 
hideCaret message directly. Occasions when the hideCaret message is sent include 
whenever the Text object receives a resignKeyWindow, mouseDown:, or keyDown: 
message. Returns self. 

See also: - showCaret 

initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes a new Text object. This method invokes the initFrame:text:alignment: 
method with the size and location specified by frameRect. Text alignment is set to 
NX_LEFTALIGNED. Returns self. 

See also: - initFrame:text:alignment: 

mitFrame:text:alignment: 

- initFrame: (const NXRect *)frameRect 

text: (const char *)theText 
alignment: (int )mode 

Initializes a new Text object. This is the designated initializer for Text objects: If you 
subclass Text, your subclass’s designated initializer must maintain the initializer chain 
by sending a message to super to invoke this method. See the introduction to the class 
specifications for more information. 

The three arguments specify the Text object’s frame rectangle, its text, and the 
alignment of the text. Th e, frameRect argument specifies the Text object’s location and 
size in its superview’s coordinates. A Text object’s superview must be a flipped view 
that’s neither scaled nor rotated. The second argument, theText, is a null-terminated 
array of characters. The mode argument determines how the text is drawn with respect 
to the bodyRect: 

Constant Alignment 

NX_LEFTALIGNED Flush to left edge of the bodyRect. 

NX_RIGHTALIGNED Flush to right edge of the bodyRect. 

NX_CENTERED Each line centered between left and right edges of the 

bodyRect. 

NX_JUSTIFIED Flush to left and right edges of the bodyRect; 

justified. Not yet implemented. 
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The Text object returned by this method uses the class object’s default font (see 
setDefaultFont:) and uses NXEditorFilter() as its character filter. It wraps words 
whose length exceeds the line length. It sets its View properties to draw in its 
superview, to be flipped, and to be transparent. For more efficient editing, you can send 
a setOpaque: message to make the Text object opaque. 

Text editing is designed to work in buffered windows only. In a nonretained or retained 
window, editing text in a Text object causes flickering. (However, to get better drawing 
performance without causing flickering during editing, see 

setRetained WhileDrawing:). 

Returns self. 

See also: - initFrame: 

isEditable 

- (BOOL)isEditable 

Returns YES if the text can be edited, NO if not. 

See also: - isSelectable, - setDelegate: 

isFontPanelEnabled 

- (BOOL)isFontPanelEnabled 

Returns YES if the Text object will respond to the Font panel, NO if not. The default 
value is YES. 

See also: - setFontPanelEnabled: 

isHorizResizable 

- (BOOL)isHorizResizable 

Returns YES if the text can automatically change size horizontally, NO if not. The 
default value is NO. 

See also: - setVertResizable:, - isVertResizable, - setHorizResizable: 

isMonoFont 

- (BOOL)isMonoFont 

Returns YES if the Text object allows multiple paragraph styles and fonts, NO if not. 
See also: - setMonoFont: 
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isRetainedWhileDrawing 

- (BOOL)isRetainedWhileDrawing 

Returns YES if the Text object automatically changes its window’s buffering type from 
buffered to retained whenever it redraws itself, NO if not. 

See also: - setRetainedWhileDrawing:, - drawSelf:: 

isRuIerVisible 

- (BOOL)isRulerVisible 

Returns YES if the ruler is visible in the Text object’s superview, a ScrollView; 
otherwise, returns NO. 

See also: - toggleRuler: 

isSelectable 

- (BOOL)isSelectable 

Returns YES if the text can be selected, NO if not. 

See also: - isEditable, - setDelegate: 

isVertResizable 

- (BOOL)isVertResizable 

Returns YES if the text can automatically change size vertically, NO if not. The default 
value is NO. 

See also: - setVertResizable:, - setHorizResizable:, - isHorizResizable 
key Down: 

- keyDown:(NXEvent *)theEvent 

Analyzes key-down events received by the Text object. keyDown: first uses the Text 
object’s character filter function to determine whether the event should be interpreted 
as a command to move the cursor or as a command to end the Text object’s status as the 
first responder. If the latter, the Text object’s delegate is given an opportunity to prevent 
the change. 

If the event represents a character that should be added to the text, the Text object sets 
up a modal event loop to process it along with other key-down events as they’re 
received. The text is redrawn, and then keyDown: notifies the delegate that the text has 
changed. This message is sent by the system in response to keyboard events. You never 
send this message, though you may want to override it. 

See also: - setCharFilter:, - setDelegate:, - getNextEvent:waitFor: (Application) 
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lineFromPosition: 

- (int)lineFromPosition:(int)pas7?f<9/i 

Returns the line number that contains the character at position. To get more 
information about the contents of the Text object, use the stream returned by the stream 
method to read the contents of the Text object. 

See also: - positionFromLine:, - stream 
lineHeight 

- (NXCoord)lineHeight 

Returns the default line height for the Text object. 

See also: - setLineHeight: 

mouseDown: 

- mouseDown :(NXEvent *)theEvent 

Responds to mouse-down events. When a Text object that allows selection receives a 
mouseDown: message, it tracks mouse-dragged events and responds by adjusting the 
selection and autoscrolling, if necessary. You never send this message, though you may 
want to override it. 

See also: - setEditable:, - setDelegate:, - getNextEvent:waitFor: (Application) 
moveCaret: 

- moveCaret: (unsigned short)theKey 

Moves the caret either left, right, up, or down if theKey is NX_LEFT, NX_RIGHT, 
NX_UP, or NX_DOWN. If theKey isn’t one of these four values, the caret doesn’t 
move. Returns self. 

See also: - keyDown: 
moveTo:: 

- moveTo: (NXCoord)* :(NXCoord)y 

Moves the origin of the Text object’s frame rectangle to (x, y) in its superview’s 
coordinates. Returns self. 

See also: - moveTo:: (View) 


Application Kit Classes: Text 2-585 



overstrikeDiacriticals 

- (int)overstrikeDiacriticals 

Unimplemented. 

paste: 

- x>a.stz'.sender 

Places the contents of the selection pasteboard into the Text object at the position of the 
current selection. If the selection is zero-width, the text is inserted at the caret. If the 
selection has positive width, the selection is replaced by the contents of the pasteboard. 
In either case, the text is re wrapped and redrawn. 

Before the paste operation, a textDidChange: message is sent to the delegate, 
assuming that this is the first change since the Text object became the first responder 
and that the delegate implements the method. After the paste operation, the delegate 
receives a textDidGetKeysiisEmpty: message, if it implements the method. 

sender is the id of the sending object, paste: returns nil if the pasteboard can provide 
neither NXAsciiPboardType nor NXRTFPboardType format types; otherwise, returns 
self. 

See also: - copy:, - cut:, - delete:, - copyFont:, - copyRuler:, - pasteFont:, 

- pasteRuler:, - textDidGetKeys:isEmpty:, - textDidChange: 

pasteFont: 

- pasteFont: sender 

Takes font information from the font pasteboard and applies it to the current selection. 
If the selection is zero-width, only those characters subsequently entered at the 
insertion point are affected. 

pasteFont: works only with rich Text objects (see setMonoFont:). Attempting to 
paste a font into a plain Text object generates a system beep without altering any fonts. 

Before the paste operation, a textDidChange: message is sent to the delegate, 
assuming that this is the first change since the Text object became the first responder 
and that the delegate implements the method. After the paste operation, the delegate 
receives a textDidGetKeys:isEmpty: message, if it implements the method. 

sender is the id of the sending object. After the font is pasted, the text is rewrapped and 
redrawn. pasteFont: returns nil if the pasteboard has no data of the type 
NXFontPboardType; otherwise, returns self. 

See also: - copyFont:, - copyRuler:, - pasteRuler:, - copy:, - cut:, - delete:, 

- paste:, - setMonoFont: - textDidGetKeys:isEmpty:, - textDidChange: 
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pasteRuler: 

- pasteRuler ‘.sender 

Takes ruler information from the ruler pasteboard and applies it to the paragraph or 
paragraphs marked by the current selection. The ruler controls a paragraph’s text 
alignment, tab settings, and indentation. 

pasteRuler: works only with rich Text objects (see setMonoFont:). Attempting to 
paste a ruler into a plain Text object generates a system beep without altering any ruler 
settings. 

Before the paste operation, a textDidChange: message is sent to the delegate, 
assuming that this is the first change since the Text object became the first responder 
and that the delegate implements the method. After the paste operation, the delegate 
receives a textDidGetKeys:isEmpty: message, if it implements the method. 

sender is the id of the sending object. After the ruler is pasted, the text is rewrapped 
and redrawn. If the ruler is visible, it’s also updated. pasteRuler: returns nil if the 
pasteboard has no data of the type NXRulerPboardType; otherwise, returns self. 

See also: - copyRuler:, - copyFont:, - pasteFont:, - copy:, - cut:, - delete:, 

- paste:, - setMonoFont: - textDidGetKeys:isEmpty:, - textDidChange: 

positionF r omLine: 

- (int)positionFromLine: (incline 

Returns the character position of the line numbered line. Each line is terminated by a 
Return character, and the first line in a Text object is line 1. To find the length of a line, 
you can send the positionFromLine: message with two successive lines, and use the 
difference of the two to get the line length. To get more information about the contents 
of the Text object, use the stream returned by the stream method to read the contents 
of the Text object. 

See also: - lineFromPosition:, - stream 
postSelSmar tT able 

- (const unsigned char *)postSelSmartTabIe 

Returns a pointer to the table that specifies which characters on the right end of a 
selection are treated as equivalent to a space character. 

See also: - setPostSelSmartTable:, - setPreSelSmartTable:, - preSelSmartTable 
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preSelSmartTable 

- (const unsigned char *)preSelSmartTable 

Returns a pointer to the table that specifies which characters on the left end of a 
selection are treated as equivalent to a space character. 

See also: - setPreSelSmartTable:, - setPostSelSmartTable:, - postSelSmartTable 
read: 

- read:(NXTypedStream *)stream 

Reads the Text object in from the typed stream stream. A read: message is sent in 
response to archiving; you never send this message directly. Returns self. 

readRichText: 

- readRichText:(NXStream *)stream 

Reads RTF text from stream into the Text object and formats the text accordingly. The 
Text object is resized to be large enough for all the text to be visible. The NeXTStep 
Concepts manual lists the RTF directives that the Text object understands. RTF 
directives that aren’t implemented are ignored. Returns self. 

See also: - writeRichText: 
readRichText:atPosition: 

- readRichText:(NXStream *)stream atPosition: (int)position 

Reads RTF text from stream into the Text object’s text at position and formats the text 
accordingly. You never send this message, but may want to override it to read special 
RTF directives while the Text object is reading RTF data. If there is a delegate, and it 
implements the method, the Text object sends it a textWillReadRichTexf.atPosition 
message. Returns self. 

readSelectionFromPasteboar d: 

- readSelectionFromPasteboard:p£><?arfi? 

Replaces the current selection with data from the supplied Pasteboard object, pboard. 
When the user chooses a command in the Services menu, a 
writeSelectionToPasteboard:types: message is sent to the first responder. This 
message is followed by a readSelectionFromPasteboard: message, if the command 
requires the requesting application to replace its selection with data from the service 
provider. 

See also: - writeSelectionToPasteboardrtypes:, 

- validRequestorFor Sendiy pe: andReturnTypes: 
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readText: 

- readText: (NXStream *)stream 

Reads new text into the Text object from stream. All previous text is deleted. The Text 
object wraps and redraws the new text if autodisplay is enabled. This method doesn’t 
affect the object’s frame or bounds rectangle. To resize the text rectangle to make the 
text entirely visible, use the sizeToFit method. Returns self. This method raises an 
NX_textBadRead exception if an error occurs while reading from stream. 

See also: - setSel::, - setText:, - readRichText:, - sizeToFit 

r enewFont: size: style: text: frame: tag: 

- renewFont: (const char *)newFontName 

size: (float )newFontS ize 
style: (int )newFontStyle 
text:(const char *)newText 
frame: (const NXRect *)newFrame 
tag:(int)newTag 

Resets a Text object so that it can be reused to draw or edit another piece of text. If 
newText is NULL, the new text is the same as the previous text. newTag sets the Text 
object’s tag. A font object is created with newFontName, newFontSize , and 
newFontStyle. This method is a convenient cover for the renewRuns:text:frame:tag: 
method. Returns self. 

See also: - renewRuns:text:frame:tag:, - setText: 

renewFont:text:frame:tag: 

- renewFont inewFontld 

text: (const char *)newText 
frame:(const NXRect *)newFrame 
tag:(int )newTag 

Resets a Text object so that it can be reused to draw or edit another piece of text. If 
newText is NULL, the new text is the same as the previous text. newTag sets a Text 
object’s tag. This method is a convenient cover for the renewRuns:text:frame:tag: 
method. Returns self. 

See also: - setText: 
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r ene wRuns: text: frame: tag: 

- renewRuns:(NXRun Array *)newRuns 

text: (const char *)newText 
frame:(const NXRect *)newFrame 
tag:(int)newTag 

Resets a Text object so that it can be reused to draw or edit another piece of text. If 
newRuns is NULL, the new text uses the same runs as the previous text. If newText is 
NULL, the new text is the same as the previous text. newTag sets a Text object’s tag. 
Returns self. 

See also: - setText: 
replaceSel: 

- replaceSel ’.(const char *)aString 

Replaces the current selection with text from aString, a null-terminated character 
string, and then rewraps and redisplays the text. Returns self. 

See also: - replaceSel’.length: 
replaceSel: length: 

- replaceSel: (const char *)aString length: (int )length 

Replaces the current selection with length characters of text from aString , and then 
rewraps and redisplays the text. Returns self. 

See also: - replaceSel: 

replaceSel: length: r uns: 

- replaceSel:(const char *)aString 

length : (int )length 

runs: (NXRunArray *)insertRuns 

Replaces the current selection with length characters of text from aString , using 
insertRuns to describe the run changes. Another way to replace the selection with 
multiple-run text is with replaceSelWithRichText:. 

After replacing the selection, this method rewraps and redisplays the text. Returns self. 
See also: - replaceSel:, - replaceSelWithRichText: 
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replaceSelWithCell: 

- replaceSelWithCell:ce// 

Replaces the current selection with the image provided by cell. This method works 
only with rich Text objects. (See setMonoFont:.) 

The image is treated like a single character. Its height and width are determined by 
sending the Cell a calcCellSize: message. The height determines the line height of the 
line containing the image, and the width sets the character placement in the line. The 
image is drawn by sending the Cell a drawSelf-.inView: message. 

After receiving a replaceSelWithCell: message, a Text object rewraps and redisplays 
its contents. Returns self. 

See also: - setMonoFont:, - calcCellSize: (Cell), - drawSelf:inView: (Cell) 

replaceSelWithRichText: 

- replaceSelWithRichText: (NXStream *)stream 

Replaces the current selection with RTF data from stream. A 
replaceSelWithRichText: message is sent in response to pasting RTF data from the 
pasteboard. 

After replacing the selection, this method rewraps and redisplays the text. Returns self. 
See also: - replaceSel:, - replaceSel:length:runs: 

replaceSelWithView: 

- replaceSelW ith View:v/evv 

Unimplemented. 

resignFirstResponder 

- resignFirstResponder 

Asks the Text object’s delegate for permission before letting the Text object cease being 
the first responder. If the delegate’s textWillEnd: method returns a nonzero value, the 
Text object remains the first responder, the entire text becomes the selection, and this 
method returns nil. Otherwise, resignFirstResponder returns self. 

resignFirstResponder messages are sent for you; you never send them yourself. 

See also: - setDelegate:, -acceptsFirstResponder, - selectError 
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resignKeyWindow 

- resignKeyWindow 

Deactivates the caret when the Text object’s window ceases to be the key window. A 
Window, before it ceases to be the application’s key window, sends this message to its 
first responder. You should never directly send this message to a Text object. Returns 
self. 

See also: - becomeKeyWindow 
resizeText:: 

- resizeText: (const NXRect *)oldBounds :(const NXRect *)maxRect 

Causes the superview to redraw exposed portions of itself after the Text object’s frame 
has changed in response to editing. You never send a resizeText:: message directly, but 
you might override it. oldBounds can differ from bounds in origin.x and size.width 
and size.height. Returns self. 


scanFunc 

- (NXTextFunc)scanFunc 

Returns the scan function, the function that calculates the contents of each line of text 
given the line width, font size, text alignment, and other factors. NXScanALine() is 
the default scan function. 

See also: - setScanFunc:, - setDrawFunc: 

scrollSelToVisible 

- scrollSelToVisible 

Scrolls the text so that the selection is visible. Returns self. 

select All: 

- select All ^crater 

Attempts to make a Text object the first responder and, if successful, then selects all of 
its text. Returns self. 

See also: - selectError, - setSel:: 
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selectError 

- selectError 

Makes the entire text the selection and highlights it. The Text object applies this 
method if the delegate requires the Text object to maintain its status as the first 
responder. You rarely need to send a selectError message directly, although you may 
want to override it. To highlight a portion of the text, use setSel::. Returns self. 

See also: - setSel::, - setDelegate:, - selectAll: 

selectNull 

- selectNull 

Removes the selection and makes the highlighting (or caret, if the selection is 
zero-length) disappear. The Text object’s delegate isn’t notified of the change. The 
Text object sends a selectNull message whenever it needs to end the current selection 
but retain its status as the first responder; you rarely need to override this method or 
send selectNull messages directly. Returns self. 

See also: - setSel::, - selectError, - selectAll:, - getSel:: 

selectText: 

- selectText '.sender 

Attempts to make a Text object the first responder and, if successful, then selects all of 
its text. Returns self. 

See also: - selectAll:, - setSel:: 

selGray 

- (float)selGray 

Not yet implemented. 

See also: - setSelGray:, - setBackgroundGray:, - backgroundGray, 

- setTextGray:, - textGray 
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setAlignment: 

- setAlignment :(int)mode 


Sets the default alignment for the text, mode can have these values 
(NXJLEFTALIGNED is the default): 

Constant Alignment 

NXJLEFTALIGNED Flush to left edge of the bodyRect. 


NXJRIGHTALIGNED Flush to right edge of the bodyRect. 

NX_CENTERED Each line centered between left and right edges of the 

bodyRect. 


NX_JUSTIFIED Flush to left and right edges of the bodyRect; 

justified. Not yet implemented. 


setAlignment: doesn’t rewrap or redraw the text. Send a calcLine message if you want 
the text rewrapped and redrawn after you reset the alignment. Returns self. 


See also: - alignment, - calcLine, - alignSelLeft:, - alignSelCenter:, 
- alignSelRight: 


setBackgroundColor: 

- setBackgroundColor: (NXColor)co/or 

Sets color as the background color for the Text object, color is an NXColor structure 
as defined in appkit/color.h. If the Text object’s window and screen allow it, this color 
is displayed the next time the text is redrawn. A setBackgroundColor: message 
doesn’t cause the text to be redrawn. Returns self. 

See also: - setBackgroundGray:, - backgroundGray:, - backgroundColor, 

- setTextGray:, - textGray, - setTextColor:, - textColor, - setSelGray:, 

- selGray, - setSelColor: 
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setBackgroundGray: 

- setBackgroundGray:(float)vtf/«e 

Sets the gray value for the background of the text, value should lie in the range from 
0.0 (indicating black) to 1.0 (indicating white). To specify one of the four pure shades 
of gray, use one of these constants: 

Constant Shade 

NX_WHITE White 

NX_LTGRAY Light gray 

NX_DKGRAY Dark gray 

NX_BLACK Black 

A setBackgroundGray: message doesn’t cause the text to be redrawn. Returns self. 

See also: - backgroundGray:, - setBackgroundColor:, - backgroundCoIor, 
-setTextGray:, - textGray, - setTextColor:, - textColor, - setSelGray:, - selGray, 

- setSelColor: 

setBreakTable: 

- setBreakTable: (const NXFSM *)aTable 

Sets the break table, the finite-state machine table that the Text object uses to determine 
word boundaries. Returns self. 

See also: - breakTable 
setCharCategoryTable: 

- setCharCategoryTable: (const unsigned char *)aTable 

Sets the character category table, the table that maps ASCII characters to character 
categories. Returns self. 

See also: - charCategoryTable 
setCharFilter: 

- setCharFilter: (NXCharFilterFunc)tfFw«c 

Sets the character filter function, the function that analyzes each character the user 
enters. The Text object has two character filter functions: NXFieldFilter() and 
NXEditorFilterQ. NXFieldFilter() interprets Tab and Return characters as 
commands to end the Text object’s status as the first responder. NXEditorFilter(), the 
default filter function, accepts Tab and Return characters into the text. Returns self. 

See also: - charFilter 
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setCharWrap: 

- setCharWrap:(BOOL)7fag 

Sets how words whose length exceeds the line length should be treated. If YES, long 
words are wrapped on a character basis. If NO, long words are truncated at the 
boundary of the bodyRect. Returns self. 

See also: - charWrap 
setClickTable: 

- setClickTable: (const NXFSM *)aTable 

Sets the finite-state machine table that defines word boundaries for double-click 
selection. Returns self. 

See also: - clickTable 

setDelegate: 

- setDelegat eianObject 

Sets the Text object’s delegate. In response to user input, the Text object can send the 
delegate any of several notification messages. See the introduction to this class 
specification for more information. Returns self. 

See also: - delegate, - acceptsFirstResponder, - resignFirstResponder 

setDescentLine: 

- setDescentLine:(NXCoord)va/we 

Sets the default descent line for the text. The descent line is the distance from the 
bottom of a line of text to the base line of the text. setDescentLine: neither rewraps 
nor redraws the text. Send a calcLine message if you want the text rewrapped and 
redrawn after you reset the descent line. Returns self. 

See also: - descentLine, - calcLine 
setDrawFunc: 

- setDrawFunc :(NXTextFunc)aF««c 

Sets the draw function, the function that’s called to draw each line of text. 
NXDrawALine() is the default draw function. Returns self. 

See also: - drawFunc, - setScanFunc: 
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setEditable: 


- setEditable: (BOOL)flag 

Sets whether the text can be edited. If flag is YES, the text is editable; if NO, the text 
is read-only. By default, text is editable. 

Use setEditable: if you don’t expect the text’s edit status to change. If your application 
needs to change the text’s edit status repeatedly, have the text’s delegate implement the 
appropriate notification methods (see setDelegate:). Returns self. 

See also: - isEditable, - setDelegate: 

setFont: 

- setFont ifontObj 

Sets the font for the entire text. The entire text is then rewrapped and redrawn. Returns 
self. 

See also: - setFont:paraStyle:, - setSelFont: 
setFont: paraStyle: 

- setFont ifontObj paraStyle: (void *)paraStyle 

Sets the font and paragraph style for the entire text. The text is then rewrapped and 
redrawn. The paragraph style controls such features as tab stops and line indentation. 
Returns self. 

See also: - setFont:, - setSelFont:, - setParaStyle: 

setFontPanelEnabled: 

- setFontPanelEnabled: (BOOL)flag 

This sets whether the Text object will respond to the changeFont: message issued by 
the Font panel. If enabled, the Text object will allow the user to change the font of the 
selection for a rich Text object. For a plain Text object, the font for the entire text is 
changed. If enabled, the Text object also updates the Font panel’s font selection 
information. Returns self. 

See also: - isFontPanelEnabled 
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setHorizResizable: 

- setHorizResizab!e:(BOOL)/?<zg 

Sets whether the text can change size horizontally. If flag is YES, the Text object’s 
frame rectangle can change in the horizontal dimension in response to additions or 
deletions of text; if NO, it can’t. By default, the Text object can’t change size. Returns 
self. 

See also: - setVertResizable:, - isVertResizable, - isHorizResizable 
setLineHeight: 

- setLineHeight: (NXCoord) va/wc 

Sets the default minimum distance between adjacent lines. For a plain Text object, this 
will be the same for all lines. For rich Text objects, line heights will be increased for 
lines with larger fonts. Even if very small fonts are used, in no case will adjacent lines 
be closer than this minimum. setLineHeight: neither rewraps nor redraws the text. 
Send a calcLine message if you want the text rewrapped and redrawn after you reset 
the line height. If no line height is set, the default line height will be taken from the 
default font. Returns self. 

See also: - lineHeight, + setDefaultFont:, - calcLine 
setLocatiomofCell: 

- setLocation:(NXPoint *)origin ofCel iicell 

Sets the x and y coordinates for the Cell object specified by cell. The coordinates are 
contained in the structure referred to by origin and are interpreted as being in the Text 
object’s coordinate system. 

This method is provided for programmers who want to write their own scan functions 
and need a way to position Cell objects found in the text stream. Sending a 
setLocation:ofCell: message to a Text object that uses the standard scan function will 
have no effect on the placement of cell. Returns self. 

See also: - getLocation:ofCell:, - replaceSelWithCell: 

setMarginLeft:right:top:bottom: 

- setMarginLeft: (NXCoord )leftMargin 

right: (NXCoord)rightMargin 
top: (NXCoord )topMargin 
bottom:(NXCoord)bottomMargin 

Adjusts the dimensions of the Text object’s margins. Returns self. 

See also: - getMarginLeft:right:top:bottom: 
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setMaxSize: 

- setMaxSize:(const NXSize *)newMaxSize 

Sets the maximum size of a Text object. This maximum size is ignored if the Text 
object can’t be resized. The default maximum size is {0.0,0.0}. Returns self. 

See also: - getMaxSize:, - setMinSize: 
setMinSize: 

- setMinSize: (const NXSize *)newMinSize 

Sets the minimum size of the receiving Text object. This size is ignored if the Text 
object can’t be resized. The default minimum size is {0.0,0.0}. Returns self. 

See also: - getMinSize:, - setMaxSize: 

setMonoFont: 

- setMonoFont: (BOOL)^flg 

Sets whether the receiving Text object uses one font and paragraph style for the entire 
text. By default, a Text object allows only one font and paragraph style. Messages to 
set the font, line height, text alignment, and so on affect the entire text of such Text 
objects. Text pasted into such Text objects assume their current font and alignment 
characteristics. A Text object in this state is called a plain Text object. 

By sending a setMonoFont:NO message, multiple fonts and paragraph styles can be 
displayed in a Text object. Thereafter, font changes affect only the selected text, and 
paragraph style changes affect only the paragraph or paragraphs marked by the 
selection. The font and alignment characteristics of pasted text are maintained. A Text 
object in this state is called a rich Text object. Returns self. 

See also: - isMonoFont, - alignSelLeft:, - setSelProp:to:, - setFontPanelEnabled: 

setNoWrap 

- setNoWrap 

Sets the Text object’s breakTable and charWrap instance variables so that word wrap 
is disabled. It also sets the text alignment to NX_LEFTALIGNED. Returns self. 

$ 

See also: - setCharWrap: 

setO ver str ikeDiacr iticals: 

- setOverstrikeDiacriticals:(BOOL )flag 

Unimplemented. 
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setParaStyle: 

- setParaStyle: (void *)paraStyle 

Sets the paragraph style for the entire text. The text is then rewrapped and redrawn. 
The paragraph style controls features such as tab stops and line indentation. Returns 
self. 

See also: - setFont:, - setFont:paraSty!e:, - setSelFont: 
setPostSelSmar tTable: 

- setPostSelSmartTable:(const unsigned char *)aTable 

Sets postSelSmartTable, the table that specifies which characters on the right end of a 
selection are treated as equivalent to a space character. Returns self. 

See also: - postSelSmartTable, - setPreSelSmartTable:, - preSelSmartTable 
setPreSelSmartTable: 

- setPreSelSmartTable: (const unsigned char *)aTable 

Sets preSelSmartTable, the table that specifies which characters on the left end of a 
selection are treated as equivalent to a space character. Returns self. 

See also: - preSelSmartTable, - setPostSelSmartTable: 

setRetainedWhileDrawing: 

- setRetainedWhileDrawing: (BOOh)flag 

Sets whether the Text object automatically changes its window’s buffering type from 
buffered to retained whenever it redraws itself. Drawing directly to the screen improves 
the Text object’s perceived performance, especially if the text contains numerous fonts 
and formats. Rather than waiting until the entire text is flushed to the screen, the user 
sees the text being drawn line-by-line. 

The window’s buffering type changes to retained only while the Text object is 
redrawing itself—that is, only when the Text object’s drawSelf:: method is invoked. 
In other cases, such as when a user is entering text, the window’s buffering type is 
unaffected. This method is designed to work with Text objects that are in buffered 
windows; don’t send a setRetainedWhileDrawing: message to a Text object in a 
retained or nonretained window. Returns self. 

See also: - isRetainedWhileDrawing, - drawSelf:: 
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setScanFunc: 


- setScanFunc: (NXTextFunc)(3FM«c 

Sets the scan function, the function that calculates the contents of each line of text given 
the line width, font size, type of text alignment, and other factors. NXScanALine() is 
the default scan function. Returns self. 

See also: - scanFunc, - setDrawFunc: 
setSel:: 

- setSel :(int).start :(int )end 

Makes the Text object the first responder and then selects and highlights a portion of 
the text, start is the first character position of the selection; end is the last character 
position of the selection. To create an empty selection, start must equal end. Use 
setSel: : to select a portion of the text programmatically. Returns self. 

See also: - selectAll:, - selectError, - selectNull, - getSel:: 
setSelColor: 

- setSelColor :(NXCo\or)color 

Sets the text color of the selected text, assuming the Text object allows more than one 
paragraph style and font (see setMonoFont:). Otherwise, setSelColor: sets the text 
color for the entire text, color is an NXColor structure as defined in the header file 
appkit/color.h. After the text color is set, the text is redisplayed. Returns self. 

See also: - setBackgroundGray:, - backgroundGray:, - setBackgroundColor:, 

- backgroundColor, - setTextGray:, - textGray, - setTextColor:, - textColor, 

- setSelGray:, - selGray 

setSelectable: 

- setSelectable: (BOOL)flag 

Sets whether the text can be selected. By default, text is selectable. Returns self. 

See also: - isSelectable, - setEditable: 
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setSelFont: 


- setSelFont ifontld 

Sets the font for the selection. The text is then rewrapped and redrawn. Returns self. 
See also: - setSelFontSize:, - setSelFontStyle:, - setFont: 

setSelFont :paraStyle: 

- setSelFont ifontld paraSty!e:(void *)paraStyle 

Sets the font of the current selection to that specified by fontID. The paragraph style is 
also changed. Returns self. 

See also: - setSelFont:, - setSelFontSize:, - setSelFontStyle: 
setSelFontFamily: 

- setSelFontFamily: (const char *)fontName 

Sets the name of the font for the selection to fontName. The text is then rewrapped and 
redrawn. Returns self. 

See also: - setSelFontSize:, - setSelFontStyle: 

setSelFontSize: 

- setSelFontSize:(float)s/ze 

Sets the size of the font for the selection to size. The text is then rewrapped and 
redrawn. Returns self. 

See also: - setSelFont:, - setSelFontStyle:, - setFont: 
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setSelFontStyle: 

- setSelFontStyle:(NXFontTraitMask)rrazA 

Sets the font style for the selection. The text is then rewrapped and redrawn. The Text 
object uses the FontManager to change the various traits of the selected font. Returns 
self. 

See also: - setSelFont:, - setSelFontSize:, - setFont: 

setSelGray: 

- setSelGray:(float)vtf/w<? 

Sets the gray value of the selected text, assuming the Text object allows more than one 
paragraph style and font (see setMonoFont:). Otherwise, setSelGray: sets the gray 
value for the entire text, value should lie in the range 0.0 (indicating black) to 1.0 
(indicating white). To specify one of the four pure shades of gray, use one of these 
constants: 

Constant Shade 

NX_ WHITE White 

NX_LTGRAY Light gray 

NX_DKGRAY Dark gray 

NX_BLACK Black 

After the gray value is set, the text is redisplayed. Returns self. 

See also: - setBackgroundGray:, - backgroundGray:, - setBackgroundColor:, 

- backgroundColor, - setTextGray:, - textGray, - setTextColor:, - textColor, 

- selGray, - setSelColor: 
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setSelProp:to: 

- setSelProp :(NXParagraphProp)prop to:(NXCoord)va/ 

Sets the paragraph style for one or more paragraphs. For a plain Text object, all 
paragraphs are affected. For a rich Text object, only those paragraphs marked by the 
selection are affected, prop determines which property is modified, and val provides 
additional information needed for some properties. These constants are defined for 
prop\ 

Constant Property Affected 

NXJLEFTALIGN Text alignment. Aligns the text to the left margin, val 

is ignored. 

NX_RIGHTALIGN Text alignment. Aligns the text to the right margin. 

val is ignored. 

NX_CENTERALIGN Text alignment. Centers the text between the left and 

right margins, val is ignored. 

NX_JUSTALIGN Not yet implemented. 

NX_FIRSTINDENT Indentation of the first line, val specifies the number 

of units (in the receiver’s coordinate system) along the 
x axis to indent. 

NX_INDENT Indentation of lines other than the first line, val 

specifies the number of units (in the receiver’s 
coordinate system) along the x axis to indent. 

NX_ADDTAB Tab placement, val specifies the position on the x axis 

(in the receiver’s coordinate system) to add the new 
tab. 

NX_REMOVETAB Tab placement, val identifies the tab to be removed by 

specifying its position on the x axis (in the receiver’s 
coordinate system). 

NX__LEFTMARGIN Left margin width, val gives the new width as a 

number of units in the receiver’s coordinate system. 

NX_RIGHTMARGIN Right margin width, val gives the new width as a 

number of units in the receiver’s coordinate system. 

setSeIProp:to: sets the left and right margins by performing the 
setMarginLeft:right:top:bottom: method. For all other properties, it performs the 
setFontiparastyle: method. After the paragraph property is set, the text is rewrapped 
and redrawn. Returns self. 

See also: - alignSelCenter:, - alignSelLeft:, - alignSelRight:, - setMonoFont: 
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setTag: 

- setTag: (mt)anlnt 

Sets the Text object’s tag value to anlnt. Returns self. 

See also: - tag, - findViewWithTag: 

setText: 

- setText: (const char *)aString 

Replaces the current text with the text referred to by aString. The Text object then 
wraps and redraws the text, if autodisplay is enabled. This method doesn’t affect the 
object’s frame or bounds rectangle. To resize the text rectangle to make the text entirely 
visible, use the sizeToFit method. Returns self. 

See also: - setSel::, - readText:, - readRichText:, - sizeToFit 
setTextColor: 

- setTextColor :(NXCo\or)color 

Sets color as the text color for the entire text, color is an NXColor structure as defined 
in the header file appkit/color.h. If the Text object’s window and screen allow it, this 
color is displayed the next time the text is redrawn. setTextColor: doesn’t redraw the 
text. Returns self. 

To set the color of selected text, use setSelColor:. 

See also: - setBackgroundGray:, - backgroundGray:, - setBackgroundColor:, 

- backgroundColor, - setTextGray:, - textGray, - textColor, - setSelGray:, 

- selGray, - setSelColor: 

setTextFilter: 

- setTextFilter : (NXTextFilterFunc )aFunc 

Sets the text filter function, the function that analyzes text the user enters. 

The text filter function is called with the following arguments: 


NXTextFunc myTextFilter(id self, unsigned char *insertText, 

int *insertLength, int position); 


This function may change the contents of the text to be inserted. The pointer to the new 
text is returned, and the new length is written into the insertLength integer pointer. The 
position is where the new text is to be inserted. 

This filter is different from the character filter in that you’re given where the text is to 
be inserted and the new text that will be inserted. This enables you to write a filter to 
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do auto-indent, or a filter to allow only properly formatted floating point numbers. The 
character filter doesn’t give enough context to determine exactly what the state of the 
Text object is before and after the edit. Returns self. 

See also: -textFilter 

setTextGray: 

- setTextGray: (float) value 

Sets the gray value for the entire text, value should lie in the range 0.0 (indicating 
black) to 1.0 (indicating white). To specify one of the four pure shades of gray, use one 
of these constants: 

Constant Shade 

NX_WHITE White 

NX_LTGRAY Light gray 

NX_DKGRAY Dark gray 

NX_BLACK Black 

A setTextGray: message doesn’t cause the text to be redrawn. Returns self. 

See also: - setBackgroundGray:, - backgroundGray:, - setBackgroundColor:, 

- backgroundColor, - textGray, - setTextCoIor:, - textColor, - setSelGray:, 

- selGray, - setSelColor: 

setVertResizable: 

- setVertResizable: (BOOL)//^g 

Sets whether the text can change size vertically. If flag is YES, the Text object’s frame 
rectangle can change in the vertical dimension in response to additions or deletions of 
text; if NO, it can’t. By default, a Text object can’t change size. Returns self. 

See also: - isVertResizable, - setHorizResizable:, - isHorizResizable 

showCaret 

- showCaret 

Displays the caret. The Text object sends itself showCaret messages whenever it needs 
to redisplay the caret; you rarely need to send a showCaret message directly. 
Occasions when the showCaret message is sent include whenever a Text object 
receives becomeKeyWindow, paste:, or delete: messages. A showCaret message 
redisplays the caret only if the selection is zero-width. If the Text object is not in a 
window, or the window is not the key window, or the Text object is not editable, this 
method has no effect. Returns self. 

See also: - hideCaret 
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showGuessPanel: 

- showGuessPaneI:se/ider 

Displays a panel that offers suggested alternate spellings for a word that’s suspected of 
being misspelled. The user can either accept one of the alternates, added the word to a 
local dictionary in ~/.NeXT/LocalDictionary, or skip the word. 

A word becomes a candidate for the Guess panel’s actions by being selected as the 
result of the Text object’s receiving a checkSpelling: message. Returns self. 

See also: - checkSpelling: 
sizeTo:: 

- sizeTo: (NXCoord)vWdr/z: (NXCoord)height 

Sets the Text object’s frame rectangle to the specified width and height in its 
superview’s coordinates. This method doesn’t rewrap the text; to do that, send a 
calcLine message. Returns self. 

See also: - sizeTo:: (View) 

sizeToFit 

- sizeToFit 

Modifies the frame rectangle to completely display the text. This is often used with 
Text objects in a ScrollView. The setHorizResizable: and setVertResizable: methods 
determine whether the Text object will resize horizontally or vertically (by default, it 
won’t change size in either dimension). After receiving a calcLine message, a Text that 
is the document view of a ScrollView sends itself a sizeToFit message. See calcLine 
for the methods that send calcLine messages. Returns self. 

See also: - setHorizResizable:, - setVertResizable: 

startReadingRichT ext 

- startReadingRichText 

A startReadingRichText message is sent to the Text object just before it begins 
reading RTF data. The Text object responds by sending its delegate a 
textWillStartReadingRichText: message, assuming there is a delegate and it 
responds to this message. The delegate can then perform any required initialization. 
Alternatively, a subclass of Text could put these initialization routines in its own 
implementation of this method. Returns self. 
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stream 

- (NXStream *)stream 

Returns a pointer to a read-only stream that allows you to read the contents of the Text 
object. The returned stream is convenient for parsing the contents of the Text object or 
for implementing text searching within a text editor. The stream is valid until the Text 
object is edited. You shouldn’t keep a copy of the stream (or free the stream) after you 
finish using it. When you need the stream again, send another stream message to get 
a valid one. 

See also: - getSubstring:start:length:, - firstTextBlock, - stream 


subscript: 

- subscript:serafer 


Subscripts the selection. The text is then rewrapped and redrawn. The text is 
subscripted by 40% of the selection’s font height. Returns self. 

See also: - superscript:, - unscript: 


superscript: 

- superscript '.sender 


Superscripts the selection. The text is then rewrapped and redrawn. The text is 
superscripted by 40% of the selection’s font height. Returns self. 

See also: - subscript:, - unscript: 


tag 

- (int)tag 

Returns the Text object’s tag. 

See also: - setTag:, - findViewWithTag: 

textColor 

- (NXColor)textColor 

Returns an NXColor structure that denotes the color used for drawing text. 
See also: - setTextColor: 
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textFilter 


- (NXTextFilterFunc)textFilter 

Returns the text filter function, the function that analyzes text the user enters. By 
default, this function is NULL. 

See also: - setTextFilter: 

textGray 

- (float)textGray 

Returns the gray value used to draw the text. 

See also: - setTextGray: 

textLength 

- (int)textLength 

Returns the number of characters in a Text object. The length doesn’t include the null 
terminator (‘\0’) that getSubstring:start:length: returns if you ask for all the text in a 
Text object. 

See also: - byteLength, - getSubstring:start:length: 

toggleRuler: 

- togg\eRu\er:sender 

Controls the display of the ruler. This method has effect only if the receiving Text 
object is a subview of a Scroll View. toggleRuler: causes the Scroll View to display a 
ruler if one isn’t already present, or to remove the ruler if one is. When the ruler is 
displayed, its settings reflect the paragraph style of the paragraph containing the 
selection. 

sender is the id of the sending object. Returns nil if the receiver isn’t a subview of a 
ScrollView instance; otherwise, returns self. 

See also: - isRulerVisible:, - copyRuler:, - pasteRuler: 
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underline: 


- \xn&tr\mt:sender 

Toggles the underline attribute of text. This method has effect only if the receiving Text 
object can display multiple fonts and paragraph styles (see setMonoFont:). 

underline: adds an underline to the selected text if one doesn’t already exist or removes 
the underline if it does. If the selection is zero-width, underline: affects the underline 
attribute of text that’s subsequently entered at the insertion point. 

sender is the id of the sending object. Returns self. 

See also: - setMonoFont:, - superscript:, - subscript: 

unscript: 

- unscript '.sender 

Removes the subscript or superscript property of the current selection. The text is then 
rewrapped and redrawn. Returns self. 

See also: - subscript:, - superscript: 

validRequestorForSendType:andReturnType: 

- validRequestorForSendType:(NXAtom)sYv?/i7>/7<? 

andReturnType : (NXAtom)returnType 

Responds to a message that the Application object sends to determine which items in 
the Services menu should be enabled or disabled at any particular time. You never send 
a validRequestorForSendType:andReturniype: message directly, but you might 
override this method in a subclass of Text. 

A Text object registers for services during initialization (however, see 
excludeFromServicesMenu:). Thereafter, whenever the Text object is the first 
responder, the Application object can send it one or more 

validRequestorForSendTypeiandReturnType: messages during event processing to 
determine which Services menu items should be enabled. If the Text object can place 
data of type sendType on the pasteboard and receive data of type returnType back, it 
should return self; otherwise it should return nil. The Application object checks the 
return value to determine whether to enable or disable commands in the Services menu. 

Since an object can receive one or more of these messages per event, it’s important that 
if you override this method in a subclass of Text, the new implementation include no 
time-consuming calculations. 

See the description of validRequestorFor SendType :andReturnType: in the 
Responder class specification for more information. 
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See also: + excludeFromServicesMenu:, 

- registerServicesMenuSendTypes:andReturnTypes: (Application), 

- readSelectionFromPasteboard:, - writeSelectionToPasteboard:, 

- validRequestorForSendType:andReturnType: (Responder) 


windowChanged: 

- windowChanged inewWindow 

Notifies the receiving Text object of a change in the identity of its Window. Generally, 
the change is the result of the Text object (or one of its superviews) being removed from 
the Window’s view hierarchy. This method ensures that the caret is hidden whenever 
the window changes. Returns self. 

See also: - windowChanged: (View) 


write: 

- write :(NXTypedStream *)stream 

Writes the Text object to the typed stream stream. A write: message is sent in response 
to archiving; you never send this message directly. Returns self. 

writeRichText: 

- writeRichText: (NXStream *)stream 

Writes the contents of the Text object as RTF data to stream. The margins, fonts, 
superscripting/subscripting, text color, and text are written out in this format. See the 
. NextStep Concepts manual for the subset of RTF directives that’s supported. Returns 
self. 

See also: - writeText:, - readText: 

writeRichText:forRun:atPosition:emitDefaultRichText: 

- writeRichText: (NXStream *)stream 

forRun:(NXRun *)run 
aiPosition:(int)runPosition 
emitDefaultRichText:(BOOL *)writeDefaultRTF 

You never send this message, but may want to override it to write special RTF directives 
while the Text object is writing RTF data. Returns self. 
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writeRichText:from:to: 


- writeRichText:(NXStream *)stream 

from:(int )start 
to:(int )end 

Writes a portion of the text starting at position start to position end in RTF to stream. 
Returns self. 

See also: - writeText:, - readText: 

writeSelectionToPasteboar d :ty pes: 

- (BOOL)writeSelectionToPasteboard ipboard 

types: (NXAtom *)types 

Writes the current selection to the supplied Pasteboard object, pboard. types lists the 
data types to be copied to the pasteboard. A return value of NO indicates that the data 
of the requested types could not be provided. 

When the user chooses a command in the Services menu, a 
writeSelectionToPasteboard:types: message is sent to the first responder. This 
message is followed by a readSelectionFromPasteboard: message if the command 
requires the requesting application to replace its selection with data from the service 
provider. 

See also: - readSelectionFromPasteboard:, 

- validRequestorForSendl>pe:andReturnType: 

writeText: 

- writeText: (NXStream *)stream 

Writes the entire text to stream. If you want to write only the selected text to a stream, 
use getSel:: (to determine the extent of the selection), getSubstring:start:Iength: (to 
retrieve the text within the selected region), and then NXWrite() to write the text to the 
stream. Returns self. 

See also: - writeRichText:, - readText:, - getSubstring:start:length: 


METHODS IMPLEMENTED BY THE DELEGATE 


textDidChange: 

- textDidChange^erafer 

Responds to a message sent to the delegate after the first change to the text since the 
Text object became the first responder. The delegate receives a textWillChange: 
message immediately before receiving a textDidChange: message. 
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textDidEndrendChar: 

- textDidEndisender endChar:(unsigned short)whyEnd 

Responds to a message informing the delegate that the Text object has relinquished first 
responder status. whyEnd is the movement character (Tab, Shift-Tab, or Return) that 
caused the Text object to cease being the first responder. The delegate can use this 
information to decide which other object should become the first responder. 

textDidGetKey s: isEmpty: 

- textDidGetKeys render isEmpty :(BOOL)flag 

Responds to a message sent to the delegate after each change to the text, flag indicates 
whether the Text object contains any text after the change. 

textDidRead: paper Size: 

- textDidRead: sender paperSize:(NXSize *)paperSize 

Responds to a message informing the delegate that the Text object will read the paper 
size for the document. 

This message is sent to the delegate after the Text object reads RTF data, allowing the 
delegate to modify the paper size. paperSize is the dimensions of the paper size 
specified by the \ paperw and \ paperh RTF directives. 

See also: - text Will Write: paperSize: 

textDidResize: oldBounds: invalid: 

- textDidResize^ender 

oldBounds: (const NXRect *)oldBounds 
invalid :(NXRect *)invalidRect 

Responds to a message informing the delegate that the Text object has changed its size. 
oldBounds is the Text object’s bounds rectangle before the change. invalidRect is the 
area of the Text object’s superview that should be redrawn if the Text object has become 
smaller. 

textWillChange: 

- (BOOL)textWillChange:sender 

Responds to a message sent upon the first user input since the Text object became the 
first responder. The delegate’s textWillChange: method can prevent the text from 
being changed by returning a nonzero value. If the delegate allows the change, it 
immediately receives a textDidChange: message after the change is made. If the 
delegate doesn’t implement this method, the change is allowed by default. 
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textWillConvert:fromFont:toFont: 

- textWiIlConvert:sencfer 

fromFont:/r<9m 

toFont:fo 

Responds to a message giving the delegate the opportunity to alter the font that will be 
used for the selection. The message is sent whenever the Font panel sends a 
changeFont: message to the Text object, from is the old font that’s currently being 
changed, to is the font that’s to replace from. This method returns the font that’s to be 
used instead of the to font. 

textWillEnd: 

- (B OOL)textWillEnd : sender 

Responds to a message informing the delegate that the Text object is about to relinquish 
first responder status. The delegate’s textWillEnd: method can prevent the change by 
returning a nonzero value. If the delegate prevents the change, the entire text becomes 
selected. If the delegate doesn’t implement this method, the change is allowed by 
default. 

textWillFinishReadingRichText: 

- textWillFinishReadingRichText : sender 

Responds to a message informing the delegate that the Text object has read RTF data, 
either from the pasteboard or from a text file. 

text WillReadRichText: stream :atPosition: 

- textWillReadRichText:sY/7^c/ 

stream:(NXStream *)stream 
atPosition:(int )runPosition 

This method is the inverse operation from 

text Will WriteRichText :stream :for Run :atPosition: emitDefaultRichText: . This 
method must read the same number of characters from stream that the inverse operation 
emits. 

See also: 

- text Will W riteRichText: stream: forRun :atPosition: emitDefaultRichText: 
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textWillResize: 

- textWillResiz eisender 

Responds to a message informing the delegate that the Text object is about to change 
its size. The delegate’s textWillResize: method can specify the maximum dimensions 
of the Text object by using the setMaxSize: method. 

If the delegate doesn’t implement this method, the change is allowed by default. 

text WillSetSel: toFont: 

- textWillSetSel: sender toFont ifont 

Responds to a message giving the delegate the opportunity to change the font that the 
Text object is about to display in the Font panel, font is the font that’s about to be set 
in the Font panel. This method returns the real font to show in the Font panel. 

textWillStartReadingRichText: 

- textWillStartReadingRichText:sender 

Responds to a message informing the delegate that the Text object is about to read RTF 
data, either from the Pasteboard or from a text file. 

textWillWriterpaperSize: 

- textWillWrite:sender paperSize:(NXSize *)paperSize 

Responds to a message informing the delegate that the Text object will write out the 
paper size for the document. 

As part of its RTF output, theText object’s delegate can write out a paper size for the 
document. The delegate specifies the paper size by placing the width and height values 
(in points) in the structure referred to by paper Size. Unless the delegate specifies 
otherwise, the paper size is assumed to be 612 by 792 points (8 1/2 by 11 inches). 

See also: - textDidRead: paper Size: 
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textWiIlWriteRichText:stream:forRun:atPosition:emitDefauItRichText: 

- text Will WriteRichText:.ve/?de/- 

stream:(NXStream *)stream 
forRun:(NXRun *)run 
2 &¥osit\on\fim\)runPosition 

emitDefaultRichText:(BOOL *)writeDefaultRichText 

The delegate may choose to write additional information into the RTF output. Runs 
that have the rFIags.subclassWantRTF field set will be sent as run in this message. 
The additional information should be written to stream , in an ASCII format. The 
textWiIlReadRichText:stream:atPosition: method, which does the inverse operation 
when RTF data is read, must read the same number of characters as is written by 
textWillWriteRichText:stream:forRun:atPosition:emitDefauItRichText:. 
runPosition is the position in the text stream that run describes; the length of the run is 
in the chars field of the NXRun structure. If YES, writeDefaultRichText instructs the 
Text object to write out the normal RTF data for the run run. 

See also: - textWillReadRichText:stream:atPosition: 


METHODS IMPLEMENTED BY AN EMBEDDED GRAPHIC OBJECT 

calcCellSize: 

- calcCellSize:(NXSize *)theSize 

Responds to a message from the Text object by providing the graphic object’s width 
and height. The Text object uses this information to adjust character placement and line 
height to accommodate the display of the graphic object in the text. See the Cell class 
specification for one implementation of this method. 

See also: - calcCellSize: (Cell) 
drawSelf:inView: 

- drawSelf: (const NXRect *)rect inViewrv/ew 

Responds to a message from the Text object by drawing the graphic object within the 
given rectangle and View. The supplied View is generally the Text object itself. See 
the Cell class specification for one implementation of this method. 

See also: - drawSelf: in View: (Cell) 
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highlight:inView:lit: 

- highlight: (const NXRect *)rect inViewiv/ew lit:(BOOL)//<2£ 

Responds to a message from the Text object by highlighting or unhighlighting the 
graphic object during mouse tracking, rect is the area within view (generally the Text 
object itself) to be highlighted. If flag is YES, this method should draw the graphic 
object in its highlighted state; if NO, it should draw the graphic object in its normal 
state. See the Cell class specification for one implementation of this method. 

See also: - highlight:inView:lit: (Cell) 

readRichTextiforView: 

- readRichText:(NXStream *)stream forView:v/cw 

Responds to a message sent by the Text object when it encounters an RTF control word 
that’s associated with the graphic object’s class (see registerDirective:forClass:) . The 
graphic object should read its representation from the RTF data in the supplied stream. 
The Text object passes its id as the view argument. 

This method is the counterpart to writeRichTextrforView:. In extracting the image 
data from the stream, readRichText:forView: must read the exact number of 
characters that writeRichTextiforView: wrote in storing the image data to the stream. 

See also: - writeRichTextiforView:, - registerDirective:forClass: 
trackMouse:inRect:ofView: 

- (BOOL)trackMouse:(NXEvent *)theEvent inRect:(const NXRect *)rect 

ofView :view 

Responds to a message from the Text object by tracking the mouse while it’s within the 
specified rectangle of the supplied View. theEvent is a pointer to the mouse-down event 
that caused the Text object to send this message, rect is the area within view (generally 
the Text object) where the mouse will be tracked. See the Cell class specification for 
one implementation of this method. 

See also: - trackMouse:inRect:ofView: (Cell) 

writeRichTextiforView: 

- writeRichText:(NXStream *)stream forView:v/ew 

Responds to a message sent by the Text object when it encounters the graphic object in 
the text it’s writing to stream. The graphic object should write an RTF representation 
of its image to the supplied stream. The Text object passes its id as the view argument. 

See also: - readRichTextiforView:, - registerDirectiveiforClass: 
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CONSTANTS AND DEFINED TYPES 


#define NX TEXTPER 490 


/* Number of characters to allocate */ 
/* for each text block */ 


typedef struct _NXTextBlock { 
struct _NXTextBlock *next; 
struct NXTextBlock *prior; 


/* Next block in linked list */ 

/* Previous block in linked list */ 


struct _tbFlags 
unsigned int 
unsigned int 
} tbFlags; 
short 

unsigned char 
} NXTextBlock; 


malloced:1; 
PAD:15; 


/* True if block was malloced */ 


chars; /* Number of characters in block */ 
*text; /* The text */ 


typedef struct { 

unsigned int underline:1; 
unsigned int dummy:1; 
unsigned int subclassWantsRTF:1; 
unsigned int graphic:1; 
unsigned int RESERVED:12; 

} NXRunFlags; 

/* NXRun represents a single sequence 
typedef struct _NXRun { 


id 


font ; 

/* 

int 


chars; 

/* 

void 


*paraStyle; 

/* 




/* 

float 


textGray; 

/* 

float 


textRGBColor; 

/* 

unsigned 

char 

superscript; 

/* 

unsigned 

char 

subscript; 

/* 

id 


info; 

/* 

NXRunFlags 

rFlags; 

/* 


} NXRun; 


/* True if text is underlined */ 
/* Unused */ 

/* Obsolete */ 

/* True if graphic is present */ 


of text with a given format. */ 
Font id */ 

Number of characters in run */ 
Implementation-dependent */ 
paragraph style information.*/ 
Text gray of current run */ 

Text color of current run */ 
Superscript in points */ 
Subscript in points */ 

For subclasses of Text */ 
Indicates underline etc. */ 


/* An NXRunArray holds the array of text runs.*/ 
typedef struct _NXRunArray { 

NXChunk chunk; 

NXRun runs[l]; 

} NXRunArray; 
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/* 

* An NXBreakArray holds line break information. It's mainly an 

* array of line descriptors. Each line descriptor contains three 

* fields: 

* 

* 1) Line change bit (sign bit); set if this line defines a new 

* height 

* 2) Paragraph end bit (next to sign bit); set if the end of this 

* line ends the paragraph 

* 3) Number of characters in the line (low-order 14 bits). 

* 

* If the line change bit is set, the descriptor is the first field 

* of an NXHeightChange structure. Since this record is bracketed 

* by negative short values, the breaks array can be sequentially 

* accessed backwards and forwards. 

*/ 

typedef short NXLineDesc; /* Line descriptor */ 

typedef struct _NXHeightInfo { 

NXCoord newHeight; 

NXCoord oldHeight; 

NXLineDesc lineDesc; 

} NXHeightInfo; 

typedef struct _NXHeightChange { 

NXLineDesc lineDesc; /* Line descriptor */ 

NXHeightlnfo heightlnfo; 

} NXHeightChange; 

typedef struct _NXBreakArray { 

NXChunk chunk; 

NXLineDesc breaks[13; /* Line descriptor */ 

} NXBreakArray; 

/* 

* NXLay represents a single sequence of text in a line and records 

* everything needed to select or draw that piece. 

*/ 

typedef struct { 

unsigned int mustMove:!; /* True if lay follows lay with */ 

/* nonprinting character; e.g. Tab */ 
unsigned int isMoveChar:1; /* True if lay contains nonprinting */ 

/* character; e.g. Tab */ 

unsigned int RESERVED:14; 

} NXLayFlags; 


/* Line height from here forward*/ 
/* Height before change */ 

/* Line descriptor */ 
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typedef struct 

_NXLay { 




NXCoord 

x; 

/* 

x coordinate of moveto */ 


NXCoord 

y; 

/* 

y coordinate of moveto */ 


short 

offset; 

/* 

Offset in line for first character 

*/ 



/* 

of run */ 


short 

chars; 

/* 

Number of characters in lay */ 


id 

font; 

/* 

Font id */ 


void 

*paraStyle; 

/'* 

Implementation-dependent paragraph 

*/ 



/* 

style information */ 


NXRun 

*run; 

/* 

Run for lay */ 


NXLayFlags 

lFlags; 

/* 

Indicates lay affected by move */ 




/* 

characters */ 



} NXLay; 


/* NXLayArray holds the layout for the current line. */ 
typedef struct _NXLayArray { 

NXChunk chunk; 

NXLay lays[l]; 

} NXLayArray; 

/* NXWidthArray holds the widths for the current line. */ 
typedef struct _NXWidthArray { 

NXChunk chunk; 

NXCoord widths[1]; 

} NXWidthArray; 

/* NXCharArray holds the character array for the current line. */ 
typedef struct _NXCharArray { 

NXChunk chunk; 

unsigned char text[l]; 

} NXCharArray; 

/* 

* An NXFSM is a word definition finite-state machine transition 

* structure. 

*/ 

typedef struct _NXFSM { 

const struct _NXFSM *next; /* State to go to; NULL implies 

final state */ 

short delta; /* If final state, this undoes lookahead */ 

short token; /* If final state, negative value implies */ 

/* word is newline; 0 implies dark; */ 

/* positive implies white space */ 

} NXFSM; 
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/* Represents 

one end of 

a 

selection. */ 

typedef struct 

_NXSelPt 

{ 


int 

cp; 

/* 

Character position */ 

int 

line; 

/* 

Offset of NXLineDesc in break table */ 

NXCoord 

x; 

/* 

x coordinate */ 

NXCoord 

y; 

/* 

y coordinate */ 

int 

cist; 

/* 

Character position of first character */ 



/* 

on the line */ 

NXCoord 

ht; 

/* 

Line height */ 


} NXSelPt; 


/* Describes tabstop. */ 


typedef struct 

_NXTabStop { 



short 

kind; /* Only NX LEFTTAB implemented */ 

NXCoord 

x; /* x coordinate for stop */ 

} NXTabStop; 




/* Describes current text block 

and run. */ 

typedef struct 

NXTextCache { 



int 

curPos; 

/* 

Current position in text stream */ 

NXRun 

*curRun; 

/* 

Current run of text */ 

int 

runFirstPos; 

/* 

Character position of first */ 



/* 

character in current run */ 

NXTextBlock 

*curBlock; 

/* 

Current block of text */ 

int 

blockFirstPos ; 

/* 

Character position of first */ 



/* 

character in current block */ 

} NXTextCache; 




typedef struct 

NXLaylnfo { 



NXRect 

rect ; 

/* 

Bounds rect. for current line. */ 

NXCoord 

descent; 

/* 

Descent line for current line. */ 



/* 

Can be reset by scanFunc */ 

NXCoord 

width; 

/* 

Width of line */ 

NXCoord 

left; 

/* 

Coordinate visible at left side */ 

NXCoord 

right; 

/* 

Coord, visible at right side */ 

NXCoord 

rightIndent; 

/* 

How much white space to leave */ 



/* 

at right side of line */ 

NXLayArray 

*lays; 

/* 

Scan function fills with NXLay */ 



/* 

items */ 

NXWidthArray *widths; 

/* 

Scan function fills with */ 



/* 

character widths */ 

NXCharArray 

*chars; 

/* 

Scan function fills with */ 



/* 

characters */ 

NXTextCache 

cache; 

/* 

Cache of current block & run */ 

NXRect 

*textClipRect; 

/* 

If not NULL, the current */ 



/* 

clipping rectangle for drawing */ 
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struct _lFlags { 
unsigned int 

unsigned int 

unsigned int 

unsigned int 

unsigned int 
unsigned int 


horizCanGrow:1;/* True if scan func. should */ 

/* dynamically resize x margins */ 
vertCanGrow:1/ /* True if scan func. should */ 

/* dynamically resize y margins */ 
erase:1; /* True if draw function should */ 

/* erase before drawing */ 
pingrl; /* True if draw function should */ 

/* ping Window Server */ 

endsParagraph:1;/* True if line ends paragraph */ 
resetCache:1; /* Used by Scan function to */ 

/* reset local caches */ 


unsigned int RESERVED:10; 
} lFlags; 

} NXLaylnfo; 


/* Describes text layout and tab stops. */ 


typedef struct 

_NXTextStyle 

{ 


NXCoord 

indent1st; 

/* 

How far first line in paragraph is */ 



/* 

indented */ 

NXCoord 

indent2nd; 

/* 

How far second and subsequent lines */ 



/* 

are indented */ 

NXCoord 

lineHt; 

/* 

Line height */ 

NXCoord 

descentLine; 

/* 

Distance from baseline to */ 



/* 

bottom of line */ 

short 

alignment; 

/* 

Text alignment */ 

short 

numTabs; 

/* 

Number of tab stops */ 

NXTabStop 

*tabs; 

/* 

Array of tab stops */ 


} NXTextStyle; 

/* Text alignment modes. */ 

#define NX_LEFTALIGNED 0 
#define NX_RIGHTALIGNED 1 
#define NX_CENTERED 2 

#define NX_JUSTIFIED 3 

/* Tab stop types. */ 

#define NX_LEFTTAB 0 

/* Constants used by the character filter function. */ 


#define 

NX_ 

_BACKSPACE 

8 


#define 

NX_ 

_CR 

13 


#define 

NX 

_DELETE 

((unsigned 

short)0x7F) 

#define 

NX_ 

_BTAB 

25 


#define 

NX_ 

_ILLEGAL 

0 


#define 

NX_ 

_RETURN 

((unsigned 

short)0x10) 

#define 

NX_ 

_TAB 

((unsigned 

short)0x11) 

#define 

NX_ 

_BACKTAB 

((unsigned 

short)0x12) 

#define 

NX_ 

_LEFT 

( (unsigned 

short)0x13) 

#define 

NX_ 

_RIGHT 

( (unsigned 

short)0x14) 

#define 

NX_ 

_UP 

( (unsigned 

short)0x15) 

#define 

NX_ 

_DOWN 

( (unsigned 

short)0x16) 
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/* Paragraph properties */ 
typedef enum { 

NX_LEFTALIGN = NX_LEFTALIGNED, 

NX_RIGHTALIGN = NX_RIGHTALIGNED, 

NX_CENTERALIGN = NX_CENTERED, 

NX_JUSTALIGN = NX_JUSTIFIED, 

NX_FIRSTINDENT, 

NX_INDENT, 

NX_ADDTAB, 

NX_REMOVETAB, 

NX_LEFTMARGIN, 

NX_RIGHTMARGIN 
} NXParagraphProp; 

/* 

* Word tables for various languages. The SmartLeft and SmartRight 

* arrays are suitable as arguments for the messages 

* setPreSelSmartTable: and setPostSelSmartTable. When doing a 

* paste, if the character to the left (right) of the new word is not 

* in the left (right) table, an extra space is added on that side. 

* The CharCats tables define the character classes used in the word 

* wrap or click tables. The BreakTables are finite-state machines 

* that determine word wrapping. The ClickTables are finite-state 

* machines that determine which characters are selected when the 

* user double clicks. 

*/ 

const unsigned char * const NXEnglishSmartLeftChars; 

const unsigned char * const NXEnglishSmartRightChars; 

const unsigned char * const NXEnglishCharCatTable; 

const NXFSM * const NXEnglishBreakTable; 

const int NXEnglishBreakTableSize; 

const NXFSM * const NXEnglishNoBreakTable; 

const int NXEnglishNoBreakTableSize; 

const NXFSM * const NXEnglishClickTable; 

const int NXEnglishClickTableSize; 

const unsigned char * const NXCSmartLeftChars; 

const unsigned char * const NXCSmartRightChars; 

const unsigned char * const NXCCharCatTable; 

const NXFSM * const NXCBreakTable; 

const int NXCBreakTableSize; 

const NXFSM * const NXCClickTable; 

const int NXCClickTableSize; 

typedef int (*NXTextFunc) (id self, NXLaylnfo *layInfo); 

typedef unsigned short (*NXCharFilterFunc) (unsigned short 
charCode, int flags, unsigned short charSet); 

typedef char *(*NXTextFilterFunc) (id self, unsigned char * 
insertText, int *insertLength, int position); 
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TextField 


INHERITS FROM Control: View : Responder : Object 

DECLARED IN appkit/TextField.h 

CLASS DESCRIPTION 

The TextField class provides a Control object that can display a piece of text, select all 
or part of it if it is selectable, and edit it if it is editable. It is a good alternative to the 
Text object when you want small editable text since you don’t have to allocate memory 
for a Text object for each TextField instance—the display of the TextField is achieved 
by using a global Text object shared by objects all over your application. Moreover, 
editing and selecting are achieved by a Text object that is unique for a given Window. 
The TextField is a Control in the sense that the action message of its Cell is sent to the 
target object of its Cell when the user presses the Return key. When the user presses 
the Tab key and when there is some object in the TextField’s nextText instance variable 
that responds to the selectText: method (such as another field of data to enter), that 
object is selected. 

You can drag TextField and an accompanying TextFieldCell into an application from 
the Interface Builder Palettes panel. 


INSTANCE VARIABLES 
Inherited from Object 
Inherited from Responder 
Inherited from View 


Inherited from Control 


Declared in TextField 


nextText 


Class 

id 

NXRect 

NXRect 

id 

id 

id 

struct_vFlags 

int 

id 

struct _conFlags 

id 

id 

id 

SEL 


isa; 

nextResponder; 

frame; 

bounds; 

superview; 

subviews; 

window; 

vFlags; 

tag; 

cell; 

conFlags; 

nextText; 

previousText; 

textDelegate; 

errorAction; 


the object to select when Tab is pressed 
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previousText 

textDelegate 

errorAction 

METHOD TYPES 

Initializing the TextField Class 
Initializing a new TextField 
Enabling the TextField 
Modifying Text Attributes 

Editing Text 


Modifying Graphic Attributes 


Resizing a TextField 
Target and Action 
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object to select when Shift-Tab is pressed 

delegate for textDidEndiendChar:, etc. 

sent to target when a bad value is entered in the 
field 


+ setCellClass: 

- initFrame: 

- setEnabled: 

- isEditable 

- isSelectable 

- setEditable: 

- setSelectable: 

- selectText: 

- setNextText: 

- setPreviousText: 

- textDidGetKey s: isEmpty: 

- textDidChange: 

- textDidEndiendChar: 

- textWillChange: 

- textWillEnd: 

- backgroundColor 

- backgroundGray 

- isBezeled 

- isB ordered 

- isBackgroundTransparent 

- setBackgroundColor: 

- setBackgroundGray: 

- setBackgroundTransparent: 

- setBezeled: 

- setBordered: 

- setTextColor: 

- setTextGray: 

- textColor 

- textGray 

- sizeTo:: 

- errorAction 

- setErrorAction: 



Handling Events - acceptsFirstResponder 

- mouseDown: 

Archiving - read: 

- write: 

Assigning a Delegate - setTextDelegate: 

- textDelegate 


CLASS METHODS 

setCellClass: 

+ setCellClass iclassld 

This method initializes which subclass of TextFieldCell is used in implementing all 
TextFields. The default is TextFieldCell. If you subclass TextFieldCell to modify the 
behavior of a TextField, send this message with the class object of your subclass as the 
argument. Returns the id of the TextField class object. 

INSTANCE METHODS 

acceptsFirstResponder 

- (BOOL)acceptsFirstResponder 

Returns YES if the TextField is editable or selectable, NO otherwise. 

See also: - setEditable:, - setSelectable 

backgroundColor 

- (NXColor)backgroundColor 

Returns the background color of the TextField. 

backgroundGray 

- (float)backgroundGray 

Returns the background gray. 
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errorAction 


- (SEL)error Action 

Returns the action (a selector) that is sent to the target of the TextField upon text-editing 
errors (for example, if.the user typed something that wasn’t acceptable). 

See also: - setErrorAction:, - setEntryType: (Cell) 
initFrame: 

- initFrame ‘.(const NXRect *)frameRect 

Initializes and returns the receiver, a new instance of TextField, with default parameters 
in the given frame. The text is set to “Some Text”, the action is set to NULL, and the 
justification mode is set to NX_LEFTALIGNED. Also by default, the text is editable 
and the TextField is surrounded by a bezel. This method is the designated initializer 
for the TextField class. 

isBackgr oundT ransparent 

- (BOOL)isBackgroundTransparent 

Returns YES if the background is transparent. 

isBezeled 

- (BOOL)isBezeled 

Returns YES if the text is in a bezeled frame. 

isBordered 

- (BOOL)isBordered 

Returns YES if the text has a border around it. 

isEditable 

- (BOOL)isEditable 

Returns YES if the text is editable and selectable. 

isSelectable 

- (BOOL)isSelectable 

Returns YES if the text is selectable. 
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mouseDown: 

- mouseDown :(NXEvent *)theEvent 

You never invoke this method directly, but may override it to implement subclassses of 
the TextField class. If the receiver is editable text editing begins; if the receiver is 
selectable, text is selected as appropriate. Returns self. 

read: 

- read:(NXTypedStream *)stream 

Reads the TextField from the typed stream stream. Returns self. 

selectText: 

- selectText '.sender 

Selects all contents of the receiving TextField if it is editable or selectable. If you 
invoke this method before inserting the TextField in a view hierarchy, it has no effect. 
Returns self. 

setBackgroundColor: 

-setBackgroundColor:(NXColor)Co/orva/Mc 

Sets the background color for the TextField. Returns self. 

setBackgroundGray: 

- setBackgroundGray: (float )value 

Sets the background gray for the TextField. Returns self. 

setBackgroundTransparent: 

- setBackgroundGray :(BOOL)j7ag 

Sets the background of the TextField to transparent. Returns self. 
setBezeled: 

- setBezeled: (BOOL)flag 

If flag is YES, then a bezel will be drawn around the text. Returns self. 

setBordered: 

- setBordered :(BOOL)flag 

If flag is YES, then a 1-pixel black border will be drawn around the text. Returns self. 
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setEditable: 

- setEditable :(BOOL)flag 

If flag is YES, then the text in the TextField is made editable and selectable. If NO, 
then the text cannot be edited; it may, however, be selectable. Returns self. 

setEnabled: 

- setEnabled : (B OOL)flag 

If flag is YES, then the TextField is made active; if NO, then the TextField is made 
inactive. Redraws the text of the cell if autodisplay is on and the enabled state changes. 
Returns self. 


setError Action: 

- setErrorAction:(SEL)< 2 Sc/ec?or 

Sets the action that is sent to the target of the TextField upon text-editing errors. An 
error can occur when the user types something into a cell and the value returned when 
isEntryAcceptable: is sent to the cell is NO. This is a convenient method for enforcing 
some restrictions on what a user can type into a Cell. Returns self. 


setNextText: 

- setNextText:anObject 


Sets the nextText instance variable to anObject. If the anObject responds to 
setPreviousText: and selectText:, then it is sent a setPreviousText: message with self 
as the argument. The nextText instance variable is used to determine the TextField’s 
action when the user presses the Tab key; if nextText contains an object which 
responds to selectText:, the current TextField is deactivated and the selectText: 
message is sent to anObject. Returns self. 


setPreviousText: 

- setPreviousText:<z«0&/'ect 

Normally you never use this method directly. It’s invoked automatically by some other 
object’s setNextText: method. It sets the object that will be sent selectText: when 
Shift-Tab is pressed in the TextField. Returns self. 

setSelectable: 

- setSelectable:(BOOL)/7ag 

If flag is YES, then the TextField is made selectable but not editable. If NO, then the 
text is made static; neither editable nor selectable. Returns self. 

See also: - isEditable, - isSelectable, - setEditable 
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setTextColor: 

- setTextColor :(NXCo\or)Colorvalue 

Sets the color for text in the TextField. Returns self. 

setTextDelegate: 

- setTextY)e\eg‘dte:anObject 

Sets the object to which the TextField will forward any messages from the field editor. 
These messages include text:isEmpty:, textWillEnd:, textDidEnd:endChar:, 
textWillChange:, and textDidChange:. Returns self. 

See also: - textDelegate 

setTextGray: 

- setTextGray: (float) value 

Sets the gray used to draw the text in the TextField. Returns self. 
sizeTo:: 

- sizeTo: (float):(float )height 

If editing is occurring in the TextField, this aborts the editing. Then, after the View is 
resized, this method reselects the text so that editing can continue. Returns self. 

textColor 

- (NXColor)textColor 

Returns the color of text in the TextField. 

textDelegate 

- textDelegate 

Returns the object that receives messages that are forwarded by the TextField from the 
field editor. This object is set with the setTextDelegate: method. 

See also: - setTextDelegate: 

textDidChange: 

- texiDidChangeitextObject 

Delegates to the textDelegate. Can be overridden. Returns self. 
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textDidEnd:endChar: 


- ttxtD\6End'.textObject endChar: (unsigned short )whyEnd 

Invoked automatically when text editing ends. If editing ends because the Return key 
has been pressed, the TextField’s Cell sends its action message to its target. If the Tab 
key has been pressed, then the selectText: method is sent to the object stored in 
nextText or to self if nextText is nil. Returns self. 

textDidGetKeys: isEmpty: 

- textDidGetKeys:texr06/'<?c? isEmpty: (B OOL)flag 

Delegates to the textDelegate. You can override this method. Returns self. 

textGray 

- (float)textGray 

Returns the gray value used to draw the text in the TextField. 

textWillChange: 

- (BOOL)textWillChang eitextObject 

Invoked automatically during editing to determine if it is okay to edit this field. This 
method checks whether the TextField is editable and sends the text delegate a 
textWillChange message to allow it to respond. Returns NO if the text is editable; 
YES if the text is not editable. 

See also: - setEditable, - setTextDelegate 
textWillEnd: 

- (BOOL)textWillEnd itextObject 

Invoked automatically before text editing ends. This method returns YES if the editing 
can’t end, NO if editing can end. Determines the return value by sending the 
TextField’s cell an isEntryAcceptable: message and sending the text delegate a 
textWillEnd: message. 

write: 

- write: (NXTypedStream *) stream 

Writes the receiving TextField to the typed stream stream. Returns self. 
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TextFieldCell 


INHERITS FROM ActionCell: Cell: Object 

DECLARED IN appkit/TextFieldCell.h 


CLASS DESCRIPTION 

TextFieldCell is used when you want an NX_TEXTCELL that knows what the 
background and text gray values are. Normally, the Cell class assumes white as the 
background when bezeled, and light gray otherwise, and black text is always used. 
With TextFieldCell, you can specify those two parameters. This object is used by 
TextField. 


INSTANCE VARIABLES 
Inherited from Object 
Inherited from Cell 


Inherited from ActionCell 


Declared in TextFieldCell 


backgroundGray 

textGray 


Class 

char 

id 

struct _cFlagsl 
struct _cFlags2 

int 

id 

SEL 

float 

float 


isa; 

*contents; 

support; 

cFlagsl; 

cFlags2; 

tag; 

target; 

action; 

backgroundGray; 

textGray; 


The background gray color 
The gray used to display the text 


METHOD TYPES 

Initializing a new TextFieldCell - init 

- initTextCell: 

Copying a TextFieldCell - copy 
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Modifying Graphic Attributes 


Displaying 

Tracking the Mouse 
Archiving 


- backgroundColor 

- backgroundGray 

- isOpaque 

- setBackgroundColor: 

- setBackgroundGray: 

- isBackgroundTransparent: 

- setBackgroundTransparent: 

- setBezeled: 

- setTextAttributes: 

- setTextColor: 

- setTextGray: 

- textColor 

- textGray 

- drawInside:inView: 

- drawSelfiinView: 

- trackMouse:inRect:ofView: 

- read: 

- write: 


INSTANCE METHODS 


backgroundColor 

- (NXColor)backgroundColor 

Returns the color used to draw the background. 

backgroundGray 

- (float)backgroundGray 

Returns the gray used to draw the background. 

copy 

-copy 

Creates and returns a new TextFieldCell as a copy of the receiver. 
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dr awlnside: in V ie w: 


- drawlnside: (const NXRect *)cellFrame inView icontrolView 

Draws the inside of the TextFieldCell only (in other words, it doesn’t draw the bezels 
or border if any). This method is invoked from drawSelf:inView: and also from 
Control and its subclasses’ drawCelllnside: method (which is invoked from Cell’s 
set7yp<? Value: methods). If you subclass TextFieldCell, and you override 
drawSelf:inView:, then you must override this method as well. Returns self. 

drawSelf:inView: 

- drawSelf: (const NXRect *)cellFrame inView icontrolView 

Draws the text with the appropriate textGray and backgroundGray. Returns self. 


init 


- init 


Initializes and returns the receiver, a new instance of TextFieldCell, with the default 
title, “Field”. Other defaults are set as described in initTextCell: below. 

initTextCell: 

- initTextCell: (const char *)aString 

Initializes and returns the receiver, a new instance of TextFieldCell, with aString as its 
text. The default textGray is NX_BLACK, and the default backgroundGray is 
transparent (-1.0). 

This method is the designated initializer for TextFieldCell. Override his method if you 
create a subclass of TextFieldCell that performs its own initialization. Note that 
TextFieldCell doesn’t override Cell’s initlconCell: designated initializer; don’t use 
that method to initialize an instance of TextFieldCell. 

isBackgroundT ransparent: 

- (BOOL)isBackgroundGray: 

Returns YES if the background of the TextFieldCell is transparent. 

See also: - setBackgroundTransparent: 

isOpaque 

- (BOOL)isOpaque 

Returns YES if drawing the cell touches every bit in its frame. This will be true if the 
cell is bezeled, or if its backgroundGray is not transparent. 
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read: 


- read:(NXTypedStream *)stream 

Reads the TextFieldCell from the typed stream stream. Returns self. 

setBackgroundColor: 

- setBackgroundColor: (NXColor)C olorvalue 

Sets the background color for the TextFieldCell. Returns self. 

setBackgroundGray: 

- setBackgroundGray :(float)va/w<? 

Sets the gray that will be used to draw the background. A value of less than 0.0 will 
result in no background being drawn. If the cell is editable, it must have a background 
gray greater than or equal to 0.0. Returns self. 

setBackgroundTransparent: 

- setBackgroundGray :(BOOL)flag 

Sets the background of the TextFieldCell to transparent. Returns self. 
setBezeled: 

- setBezeled : (B OOL)flag 

Puts a bezel around the text. If the current backgroundGray is transparent, it’s 
changed to NX_WHITE. Bezeled transparent TextFields look strange, but if you want 
to have one, invoke setBackgroundGray: with -1.0 AFTER invoking setBezeled:. 

setText Attributes: 

- setTextAttributes:ter/C% 

You rarely need to override this method; you never need to invoke it. Sets the 
background and text gray levels. If the cell is disabled, then the gray level is brought 
toward the background gray by 1/3. For example, if the background gray is white, and 
the text gray is dark gray, the disabled text gray would be light gray. If the background 
gray is black and the text gray is white, then the disabled gray would be light gray. Note 
that if this cell is editable, and you have set the background gray to be transparent (in 
other words, less than 0.0), then you will get the default background gray 
(NXJLTGRAY). Also note that a TextFieldCell is transparent by default. Returns 
textObj. 

See also: - setTextGray:, - setBackgroundGray:, - setText Attributes: (Cell) 
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setTextColor: 


- setTextColor : (NXColor )Colorvalue 

Sets the color that will be used to draw the text. Returns self. 

setTextGray: 

- setTextGray : (float) va/ue 

Sets the gray that will be used to draw the text. Returns self. 

textGray 

- (float)textGray 

Returns the gray that will be used to draw the text. Returns self. 

tr ackMouse: inRect: ofV ie w: 

- (B OOL)tr ackMouse : (NXEvent 1 *)event 

inRect:(const NXRect *)aRect 
ofViewicontrolView 

Does nothing since clicking in a TextFieldCell causes editing to occur. 

write: 

- write :(NXTypedStream *)stream 

Writes the receiving TextFieldCell to the typed stream stream. Returns self. 
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INHERITS FROM 


Responder: Object 


DECLARED IN appkit/View.h 

CLASS DESCRIPTION 

View is an abstract class that provides its subclasses with a structure for drawing and 
handling events. Most of the classes defined in the Application Kit are direct or indirect 
subclasses of View. 

Every View is assigned to a Window where it can be displayed. All the Views within 
the Window are arranged in a hierarchy, with each View having a single superview and 
zero or more subviews. Each View has its own area to draw in and its own coordinate 
system, expressed as a transformation of its superview’s coordinate system. A View 
can scale, translate, or rotate its coordinates, flip the polarity of its y-axis, or use the 
same coordinate system as its superview. 

A View keeps track of its size and location in two ways: as a frame rectangle (expressed 
in its superview’s coordinate system) and as a bounds rectangle (expressed in its own 
drawing coordinates). Both are NXRect structures, defined in the header file 

appkit/graphics.h. 


INSTANCE VARIABLES 


Inherited from Object 
Inherited from Responder 
Declared in View 


Class 

isa; 

id 

nextResponder; 

NXRect 

frame; 

NXRect 

bounds; 

id 

superview; 

id 

subviews; 

id 

window; 

struct_vFlags { 


unsigned int 

noClip :1; 

unsigned int 

translatedDraw: 1; 

unsigned int 

drawInSuperview: 1; 

unsigned int 

already Flipped.T; 

unsigned int 

needsFlipped: 1; 

unsigned int 

rotatedFromBase: 1; 

unsigned int 

rotatedOrScaledFromBase: 1; 

unsigned int 

opaque: 1; 

unsigned int 

disableAutodisplay: 1; 

unsigned int 

needsDisplay.T; 

unsigned int 

validGState:l; 

unsigned int 

newGState.T; 

} 

vFlags; 
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frame 

A rectangle that specifies the size and location of 
the View in its superview’s coordinate system. 

bounds 

A rectangle that specifies the size and location of 
the View in its own coordinate system. 

superview 

The View’s parent in the view hierarchy. 

subviews 

A List object that lists the View’s immediate 
children in the view hierarchy. 

window 

The Window where the View is displayed. 

vFlags.noClip 

YES if drawing is not clipped to the frame. 

vFlags .translatedDraw 

YES if the bounds rectangle has been translated 
(that is, the bounds origin is not (0,0)). 

vFlags.drawInSuperview 

YES if the bounds origin equals the frame origin. 

vFlags. already Flipped 

YES if the View’s superview is flipped. 

vFlags .needsFlipped 

YES if the View is flipped. 

vFlags.rotatedFromBase 

YES if the View’s coordinates are rotated from 
base coordinates. 

vFlags .rotatedOrScaledFromB ase 

YES if the View’s coordinates are rotated or 
scaled from base coordinates. 

vFlags.opaque 

YES if the View is opaque. 

vFlags.disableAutodisplay 

YES if automatic display is disabled. 

vFlags.needsDisplay 

YES if the View needs to be displayed. 

vFlags.validGState 

YES if the View’s graphics state is valid. 

vFlags.newGState 

YES if the View has a new graphics state. 


METHOD TYPES 

Initializing and freeing View objects 

- initFrame: 

- init 

- free 
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Managing the View hierarchy - addSubview: 

- addSubview: irelativeTo: 

- findAncestorSharedWith: 

- isDescendantOf: 

- opaqueAncestor 

- removeFromSuperview 

- replaceSubview:with: 

- subviews 

- superview 

- window 

- windowChanged: 

Modifying the frame rectangle - frameAngle 

- getFrame: 

- moveBy:: 

- moveTo:: 

- rotateBy: 

- rotateTo: 

- setFrame: 

- sizeBy:: 

-sizeTo:: 

Resizing subviews - resizeSubviews: 

- setAutoresizeSubviews: 

- set Autosizing: 

- superviewSizeChanged: 

Modifying the coordinate system - boundsAngle 

- drawInSuperview 

- getBounds: 

- isFlipped 

- isRotatedFromBase 

- isRotatedOrScaledFromBase 

- rotate: 

- scale:: 

- setDrawOrigin:: 

- setDrawRotation: 

- setDrawSize:: 

- setFlipped: 

- translate:: 

Notifying ancestor Views - descendantFlipped: 

- descendantFrameChanged: 

- notifyAncestorWhenFrameChanged: 

- notifyWhenFlipped: 

- suspendNotify AncestorWhenFrameChanged: 
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Converting coordinates 


Graphics state objects 


Focusing 


Displaying 


Scrolling 


- centerScanRect: 

- convertPoint:fromView: 

- convertPointitoView: 

- convertPointFromSuperview: 

- convertPointToSuperview: 

- convertRect: fromView: 

- convertRect: to View: 

- convertRectFromSuperview: 

- convertRectToSuperview: 

- convertSize:fromView: 

- convertSize:toView: 

- allocateGState 

- freeGState 

- gState 

- initGState 

- renewGState 

- notifyToInitGState: 

- clipToFrame: 

- doesClip 

- setClipping: 

- isFocusView 

- lockFocus 

- unlockFocus 

- can Draw 

- display 

- display:: 

- display::: 

- displayFromOpaqueAncestor 

- displaylfNeeded 

- drawSelf:: 

- getVisibleRect: 

- isAutodisplay 

- set Autodisplay: 

- isOpaque 

- setOpaque: 

- needsDisplay 

- setNeedsDisplay: 

- shouldDrawColor 

- update 

- adjustScroll: 

- autoscroll: 

- calcUpdateRects:::: 

- invalidate:: 

- scrollPoint: 

- scrollRect:by: 

- scrollRectTo Visible: 
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Managing the cursor 


Assigning a tag 


Aiding event handling 


Icon dragging 
Printing 


Setting up pages 


- addCursorRectxursor: 

- discardCursorRects 

- removeCursorRectxursor: 

- resetCursorRects 

- findViewWithTag: 

-tag 

- acceptsFirstMouse 

- hitTest: 

- mouse :inRect: 

- performKeyEquivalent: 

- dragFile :fromRect: slideB ackxvent: 

- printPSCode: 

- faxPSCode: 

- copyPSCodelnsideito: 

- openSpoolFile: 

- spoolFile: 

- know sPagesFirst: last: 

- getRectrforPage: 

- placePrintRectioffset: 

- heightAdjustLimit 

- widthAdjustLimit 


Writing conforming PostScript - beginPSOutput 

- beginPrologueB B ox: creationDate: createdBy: 

fonts:forWhom:pages:title: 

- endHeaderComments 

- endPrologue 

- beginSetup 

- endSetup 

- adjustPageWidthNew:left:right:limit: 

- adjustPageHeightNew:top:bottom:limit: 

- beginPage:label:bBox:fonts: 

- beginPageSetupRect:placement: 

- drawSheetBorder:: 

- drawPageB order:: 

- addToPageSetup 

- endPageSetup 

- endPage 

- beginTrailer 

- endTrailer 

- endPS Output 


Archiving 


- awake 

- read: 

- write: 
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INSTANCE METHODS 


acceptsFirstMouse 

- (BOOL)acceptsFirstMouse 

Returns whether the View will accept the mouse down event which caused its window 
to be made the key window. If this method returns YES, all mouse-down events are 
passed to the View. Otherwise, the View will only receive mouse-down events when 
its window is the key window. The default behavior is to return NO. 

addCursorRect-.cursor: 

- addCursorRect:(const NXRect *)aRect cursor :anObj 

Adds a cursor rectangle to the View’s Window so that the cursor changes when it enters 
the specified rectangle of the View. You send this message in response to a 
resetCursorRects message. aRect describes the cursor rectangle in the View’s 
coordinates. anObj is a Cursor object, like NXIBeam or NXArrow. See View’s 
resetCursorRects for more information regarding when this message should be sent. 
Returns self. 

See also: - resetCursorRects 

addSubview: 

- addSubview :aView 

Links aView into the View hierarchy by making it a subview of the receiving View, 
placing it at the end of its subviews list. The receiving View is also made aView' s next 
responder. Returns nil if aView was not added as a subview because it does not inherit 
from View. Otherwise, this method returns aView. 

See also: - addSubview: :re!ativeTo:, - subviews, - removeFromSuperview, 

- initFrame:, - setNextResponder: (Responder) 

addSubview: rrelativeTo: 

- addSubview:# View 

:(int )place 

rel&tvv eToiotherView 

Links aView into the View hierarchy by making it a subview of the receiving View. 
This method is just like addSubview: with the additional flexibility of precise 
positioning of aView within the subview list. otherView is a member of the subview 
list, place can be either NX_ABOVE or NX_BELOW, which specifies the placement 
of aView relative to otherView. Since subviews are displayed from first to last in the 
subview list, the last element is “above” all others. If otherView is nil or is not a 
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member of the subview list, aView will be added to the top or bottom of the subview 
list depending on the value of place. This method returns nil if aView was not added 
as a subview because it does not inherit from View. Otherwise, it returns aView. 

See also: - addSubview:, - subviews, - removeFromSuperview, - initFrame:, 

- setNextResponder: 

addToPageSetup 

- addToPageSetup 

Allows applications to add a scaling operator to the PostScript code generated when 
printing; if you must add a scaling operator, this is the correct place to do so. This 
method is invoked by printPSCode: and faxPSCode:. By default, this method simply 
returns self; this method can be overridden by applications that implement their own 
pagination. 

See also: - beginPageSetupRect:placement: 

adjustPageHeightNew:top:bottom:limit: 

- adjustPageHeightNew:(float *)newBottom 

top: (Roa.t)oldTop 
bottom:(f[oal)oldBottom 
limit: (float )bottomLimit 

Adjusts page height for automatic pagination when printing the View. This method is 
invoked by printPSCode: and faxPSCode: to set newBottom, which will be the new 
bottom of the strip to be printed for the current page. oldTop and oldBottom are the 
current values for the horizontal strip to be printed. bottomLimit is the topmost value 
newBottom can be set to. If this limit is exceeded, newBottom is set to oldBottom. By 
default this method tries to not let the View be cut in two. All parameters are in the 
View’s own coordinate system. Returns self. 

adjustPageWidthNew:left:right:limit: 

- adjustPageWidthNew:(float *)newRight 

\eft:(f[oat)oldLeft 
right: (float )oldRight 
limit: (float )rightLimit 

Adjusts page width for automatic pagination when printing the View. This method is 
invoked by printPSCode: and faxPSCode: to set newRight, which will be the new 
right edge of the strip to be printed for the current page. oldLeft and oldRight are the 
current values for the vertical strip to be printed. rightLimit is the leftmost value 
newRight can be set to. If this limit is exceeded, newRight is set to oldRight. By default 
this method tries to not let the View be cut in two. All parameters are in the View’s own 
coordinate system. Returns self. 
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adjustScroll: 

- adjustScroll :(NXRect *)newVisible 

Allows you to correct the scroll position of a document. This method is invoked by a 
Clip View immediately prior to scrolling its document view. You may want to override 
it to provide specific scrolling behavior. newVisible will be the visible rectangle after 
the scroll. You might use this for scrolling through a table as in a spreadsheet. You 
could modify newVisible->origin such that the scroll would fall on column or row 
boundaries. Returns self. 

allocateGState 

- allocateGState 

Explicitly tells the View to allocate a graphics state object. Graphics state objects are 
Display PostScript objects that contain the entire state of the graphics environment. 
They are used by the Application Kit as a caching mechanism to save PostScript code 
used for focusing, purely as a performance optimization. You can allocate a graphics 
state object for Views that will be focused on repeatedly, but you should exercise some 
discretion as they can take a fair amount of memory. The graphics state object will be 
freed automatically when the View is freed. Returns self. 

See also: -freeGState 

autoscroll: 

- autoscroll :(NXEvent *)theEvent 

Scrolls the View when the cursor is dragged to a position outside its superview. You 
invoke this method from within a modal responder loop to cause scrolling to occur 
when the cursor is outside the View’s superview. The receiving View must be the 
document view of a Clip View for this method to have any effect. theEvent-> location 
must be in window base coordinates. You can invoke this method repeatedly so that 
scrolling continues even when there is no mouse movement. Returns nil if no scrolling 
occurs; otherwise returns self. 

See also: - autoscroll: (ClipView), - beginModaISession:for: (Application) 

awake 

- awake 

Invoked after unarchiving to allow the View to perform additional initialization. 
Returns self. 
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beginPage:label:bBox:fonts: 

- beginPage:(int )ordinalNum 

label: (const char *)aString 
bBox: (const NXRect *)pageRect 
fonts: (const char *)fontNames 

Writes a conforming Postscript page separator. This method is invoked by 
printPSCode: and faxPSCode:. 

ordinalNum specifies the page’s position in the document’s page sequence (from 1 
through n for an n-page document). 

aString is a string that contains no white space characters. It identifies the page 
according to the document’s internal numbering scheme. If aString is NULL, the 
ASCII equivalent of ordinalNum is used. 

pageRect is the rectangle enclosing all the drawing on the page about to be printed in 
the default PostScript coordinate system of the page. If pageRect is NULL, “(atend)” 
is output instead of a description of the bounding box, and the bounding box is output 
at the end of the page. 

fontNames is a string containing the names of the fonts used in this page. Each name 
should be separated by a space. If the fonts used are unknown before the page is 
printed, fontNames can be NULL. They will then be listed automatically at the end of 
the page description. Returns self. 

beginPageSetupRect:placement: 

- beginPageSetupRect: (const NXRect *)aRect 

placement: (const NXPoint *) location 

Writes the page setup section for a page. This method is invoked by printPSCode: and 
faxPSCode: after the starting comments for the page have been written. It outputs a 
PostScript save, and generates the initial coordinate transformation to set this View up 
for printing the aRect rectangle within the View. This method does a lockFocus on the 
View, which must be balanced in endPage by an unlockFocus. The save output here 
should be balanced by a PostScript restore in endPage. aRect is the rectangle in the 
View’s coordinates that is being printed, location is the offset in page coordinates of 
the rectangle on the physical page. Returns self. 

See also: - printPSCode, - endPage, - lockFocus, - addToPageSetup 
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beginPrologueBBox:creationDate:createdBy:fonts:forWhom:pages:title: 

- beginPrologueBBox: (const NXRect *)boundingBox 
creationDate:(const char *)dateCreated 
createdBy: (const char *)anApplication 
fonts: (const char *)fontNames 
forWhom:(const char *)user 
pages: (in t)numPages 
title:(const char *)aTitle 

Invoked by printPSCode: and faxPSCode: to write the start of a conforming 
PostScript header. 

boundingBox is the bounding box of the document. This rectangle should be in the 
default PostScript coordinate system on the page. If it is unknown boundingBox should 
be NULL and the system will accumulate it as pages are printed. 

dateCreated is an ASCII string containing a human readable date. If dateCreated is 
NULL the current date is used. 

anApplication is a string containing the name of the document creator. If 
anApplication is NULL then the string returned by Application’s appName method is 
used. 

fontNames is a string holding the names of the fonts used in the document. Names 
should be separated by a space. If the fonts used are unknown before the document is 
printed , fontNames should be NULL. In this case each font that is referenced by a 
findFont is written in the trailer. 

user is a string containing the name of the person the document is being printed for. If 
NULL the login name of the user is used. 

numPages specifies the number of pages in the document. If unknown at the beginning 
of printing, numPages should have a value of -1. In this case the pages are counted as 
they are generated and the resulting count is written in the trailer. 

aTitle is a string specifying the title of the document. If aTitle is NULL, then the title 
of the View’s Window is used. If the Window has no title, “Untitled” is output. Returns 
self. 

See also: - appName (Application) 


2-648 


Chapter 2: Class Specifications 



beginPSOutput 

- beginPSOutput 

Performs various initializations before actual PostScript generation begins. This 
method makes the Display PostScript context stored in the Application object’s global 
Printlnfo object into the current context. This has the effect of redirecting all PostScript 
output from the Window Server to the spool file or printer. This method is invoked by 
printPSCode: and faxPSCode: just before any PostScript is generated. Returns self. 

beginSetup 

- beginSetup 

Writes the beginning of the document setup section, which begins with a 
%%BeginSetup comment and includes a %%PaperSize comment declaring the type of 
paper being used. This method is invoked by printPSCode: and faxPSCode: at the 
start of the setup section of the document, which occurs after the prologue of the 
document has been written, but before any pages are written. This section of the output 
is intended for device setup or general initialization code. Returns self. 

beginTrailer 

- beginTrailer 

Writes the start of a conforming PostScript trailer. This method is invoked by 
printPSCode: and faxPSCode: immediately after all pages have been written. 
Returns self. 

boundsAngle 

- (float)boundsAngle 

Returns the angle of the View’s bounds rectangle relative to its frame rectangle. If the 
View’s coordinate system has been rotated, this angle will be the accumulation of all 
rotate: messages; otherwise, it will be 0.0. 

See also; - rotate:, - setDrawRotation: 
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calcUpdateRects:::: 

- (BOOL)calcUpdateRectsi(NXRect *)rects 

:(int *)rectCount 
:(NXRect *)enclRect 
:(NXRect *)goodRect 

You invoke this method to generate update rectangles for a subsequent display 
invocation, rects is an array of 3 rectangles, and rectCount will be set to the number of 
rectangles in rects that have been filled in, which will be either 0,1, or 3. enclRect is a 
rectangle that contains the entire area subject to update, and goodRect is a rectangle that 
contains the area that does not need to be updated. goodRect will be set to the 
intersection of goodRect and enclRect, or to a rectangle with an origin and size of zero 
if they do not intersect. The update rectangles are computed by finding the area in 
enclRect that isn’t included in goodRect. After the method invocation, if rectCount is 
0, no update rectangles were generated. If rectCount is 1, the area that needs to be 
updated is in rects[0]. If rectCount is 3, the areas that need to be updated are in rects[ 1] 
and rects[ 2], and rects[ 0] is the same as enclRect. 

Returns YES if any update rectangles were generated (in other words, if rectCount is 
greater than zero); otherwise returns NO. 

See also: - scrollRectiby:, NXIntersectionRect() 

canDraw 

- (BOOL)canDraw 

Informs you of whether drawing will have any result. You only need to send this 
message when you want to do drawing, but are not invoking one of the display methods. 
You should not draw or send the lockFocus: message if this returns NO. This method 
returns YES if your View has a Window object, your View’s Window object has a 
corresponding window on the Window Server, and your Window object is enabled for 
display; otherwise it returns NO. 

See also: - isDisplayEnabled (Window) 

centerScanRect: 

- centerScanRect :(NXRect *)aRect 

Converts the comers of a rectangle to lie on the center of device pixels. This is useful 
in compensating for PostScript overscanning when the coordinate system has been 
scaled. This routine converts the given rectangle to device coordinates, adjusts the 
rectangle to lie in the center of the pixels, and converts the resulting rectangle back to 
the View’s coordinate system. Returns self. 
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clipToFrame: 

- clipToFrame:(const NXRect *)frameRect 

Allows the View to do arbitrary clipping during focusing. This method is invoked from 
within the focusing mechanism if clipping is required. If you override this method, you 
must us eframeRect rather than the View’s frame instance variable, because the origins 
may not be the same due to focusing. The following example demonstrates clipping 
the View to a circular region: 

- clipToFrame:(const NXRect *)frameRect 
{ 

float x, y, radius; 

// Center the circle and pick an appropriate radius 
x = frameRect->origin.x + frameRect->size.width/2.0; 
y = frameRect->origin.y + frameRect->size.height/2.0; 
radius = frameRect->size.height/2.0; 

// Create a circular clipping path 
PSnewpath(); 

PSarc(x, y, radius, 0.0, 360.0); 

PSclosepath(); 

PSclip () ; 

return self; 

} 

If you override this method, you will probably need to send a setCopyOnScrolI:NO to 
the View’s subviews to make them scroll properly. Returns self. 

See also: - setCopyOnScroll: (ClipView) 

convertPointrfromView: 

- convertPoint:(NXPoint *)aPoint from View: a View 

Converts a point from aView’s coordinate system to the coordinate system of the 
receiving View. If aView == nil, then this method converts from window base 
coordinates. Both aView and the receiving View must belong to the same Window. 
Returns self. 

convertPoint:toView: 

- convertPoint:(NXPoint *)aPoint toView :aView 

Converts a point from the receiving View’s coordinate system to the coordinate system 
of aView. If aView == nil, then this method converts to window base coordinates. Both 
aView and the receiving View must belong to the same Window. Returns self. 


Application Kit Classes: View 2-651 



convertPointFromSuperview: 

- convertPointFromSuperview:(NXPoint *)aPoint 

Converts a point from the coordinate system of the receiving View’s superview to the 
coordinate system of the receiving View. Returns self. 

See also: - convertRectFromSuperview:, - convertPointToSuperview: 

convertPointToSuperview: 

- convertPointToSuperview: (NXPoint *)aPoint 

Converts a point from the receiving View’s coordinate system to the coordinate system 
of its superview. Returns self. 

See also: - convertPointFromSuperview:, - convertPoint:fromView: 

convertRect:fromView: 

- convertRect:(NXRect *)aRect fromView:aVi'ew 

Converts a rectangle from aView’s coordinate system to the coordinate system of the 
receiving View. aRect is a pointer to the rectangle to be converted. Both aView and the 
receiving View must belong to the same Window. Returns self. 

convertRectitoView: 

- convertRect:(NXRect *)aRect to View :aView 

Converts a rectangle from the receiving View’s coordinate system to the coordinate 
system of aView. aRect is a pointer to the rectangle to be converted. Both aView and 
the receiving View must belong to the same Window. Returns self. 

convertRectFromSuperview: 

- convertRectFromSuperview: (NXRect *)aRect 

Converts a rectangle from the coordinate system of the receiving View’s superview to 
the coordinate system of the receiving View. Returns self. 

See also: - convertRectToSuperview: 

con vertRectT oSuperview: 

- convertRectToSuperview: (NXRect *)aRect 

Converts a rectangle from the receiving View’s coordinate system to the coordinate 
system of its superview. Returns self. 

See also: - convertRectFromSuperview: 
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convertSizerfromView: 

- convertSize:(NXSize *)aSize fromView^Vzew 

Converts asize (a vector) from the coordinate system of aView to the coordinate system 
of the receiving View. Both aView and the receiving View must belong to the same 
Window. Returns self. 

See also: - convertSize.'toView: 

converts ize: to View: 

- convertSize:(NXSize *)aSize to View :aView 

Converts asize (a vector) from the receiving View’s coordinate system to the coordinate 
system of aView. Both aView and the receiving View must belong to the same Window. 
Returns self. 

See also: - convertSize: from View: 
copyPSCodeInside:to: 

- copyPSCodeInside:(const NXRect *)rect to:(NXStream *)stream 

Generates PostScript code for the View and all its subviews for the area indicated by 
red. The PostScript code is written to the NXStream stream. Returns self, assuming 
no exception is raised in the generation of PostScript code. If an exception is raised, 
control is given to the appropriate error handler, and this method does not return. 

See also: NX_RAISE() 

descendantFlipped: 

- descendantFlipped '.sender 

Notifies the receiving View that sender, a View below the receiving View in the view 
hierarchy, had its coordinate system flipped. A descendantFlipped: message is sent 
from the setFlipped: method if a notifyWhenFlipped:YES message was previously 
sent to sender. 

View’s default implementation of this method simply passes the message to the 
receiving View’s superview, and returns the superview’s return value. View subclasses 
should override this method to respond to the message as required. In the Application 
Kit, Clip View overrides this method to keep its coordinate system aligned with its 
document view. 

See also: - notifyWhenFlipped:, - setFlipped:, - descendantFlipped: (ClipView) 
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descendantFrameChanged: 

- descendantFrameChanged ‘.sender 

Notifies the receiving View that sender , a View below the receiving View in the view 
hierarchy, was resized or moved. A descendantFrameChanged: message is sent from 
the sizeTo:: and moveTo:: methods if a notifyAncestorWhenFrameChanged:YES 
message was previously sent to sender. 

View’s default implementation of this method simply passes the message to the 
receiving View’s superview, and returns the superview’s return value. View subclasses 
should override this method to respond to the message as required. In the Application 
Kit, the Clip View class overrides this method to notify the ScrollView to reset scroller 
knobs when the document view’s frame is changed. 

See also: - notify Ancestor WhenFrameC hanged:, - sizeTo::, - moveTo:: 

discardCursorRects 

- discardCursorRects 

Removes all cursor rectangles for the View. You rarely invoke this method; typically 
you invalidate the cursor rectangles which forces them to get reset. Returns self. 

See also: - resetCursorRects, - discardCursorRects (Window), 

- invalidateCursorRectsForView: (Window) 

display 

- display 

Displays the View and its subviews. Returns self. This method is equivalent to: 

[<receiver> display:(NXRect *)0 :0 :NO] ; 

See also: - display:::, - drawSelf:: 
display:: 

- display: (const NXRect *)rects :(int)rectCount 

Displays the View and its subviews. The rectangles are specified in the receiving 
View’s coordinate system. Returns self. This method is equivalent to: 

[<receiver> display:rects :rectCount :NO]; 

See also: - display:::, - drawSelf:: 
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display::: 

- display: (const NXRect *)rects 

:{m\)rectCount 

:(BOOL)clipFlag 

Displays the View and its subviews by invoking the lockFocus, drawSelf::, and 
unlockFocus methods, rects is an array of drawing rectangles in the receiving View’s 
coordinate system; they’re used to restrict what is displayed. rectCount is the number 
of valid rectangles in rects (0, 1, or 3). 

If rectCount is 3, then rects[0] should contain the smallest rectangle that completely 
encloses rects[ 1] and rects[ 2], the two rectangles that actually specify the regions to be 
displayed. 

If rectCount is 1, rects[ 0] should specify the region to be displayed. 

If rectCount is 0 or rects is NULL, the View’s visible rectangle is substituted for 
rects[ 0] and a value of 1 is used for rectCount. 

In any case, the rectangles in rects are intersected against the visible rectangle. 

This method doesn’t display a subview unless it falls at least partially inside rects[ 0] if 
rectCount is 1, or inside either rects[ 1] or rects[ 2] if rectCount is 3. When this method 
is applied recursively to each subview, the drawing rectangles are translated to the 
subview’s coordinate system and intersected with its bounds rectangle to produce a new 
array, rects and rectCount are then passed as arguments to each View’s drawSelf:: 
method. 

If clip Flag is YES, this method clips to the drawing rectangles. Clipping isn’t done 
recursively for each subview, however. If this method succeeds in displaying the View, 
the flag indicating that the View needs to be displayed is cleared. Returns self. 

See also: - display, - display::, - drawSelf::, - needsDisplay, - update, 

- displayFromOpaqueAncestor::: 

displayFr omOpaque Ancestor::: 

- displayFromOpaqueAncestor:(const NXRect *)rects 

:(int )rectCount 
:(BOOL )clipFlag 

Correctly displays Views that aren’t opaque. This method searches from the View up 
the View hierarchy for an opaque ancestor View. The rectangles specified by rects are 
copied and then converted to the opaque View’s coordinates and display::: is sent to 
the opaque View. If the receiving View is opaque, this method has the same effect as 
display:::. Returns self. 

See also: - display:::, - isOpaque, - setOpaque: 
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displayIfNeeded 

- displayIfNeeded 

Descends the View hierarchy starting at the receiving View and sends a display 
message to each View that needs to be displayed, as indicated by each View’s 
needsDisplay flag. This is useful when you wish to disable display in the Window, 
modify a series of Views, and then display only the ones whose appearance has 
changed. Returns self. 

See also: - display, - needsDisplay 

doesClip 

- (BOOL)doesCIip 

Returns whether this View will be clipped to its frame when it is drawn. Clipping is on 
by default. 

See also: - setCIipping: 

dragFile:fromRect:slideBack:event: 

- dragFile: (const char *) filename 

fromRect:(NXRect *)rect 
slideBack:(BOOL) aFlag 
event :(NXEvent *)event 

Allows a file icon to be dragged from the View to any application that accepts files. You 
typically invoke this method from within your View’s mouseDown: method when you 
receive a mouse event on an icon representing a file. This method sends a message to 
the Workspace Manager, and the Workspace Manager takes care of the actual file 
dragging. The Workspace manager finds the icon for filename and tracks the mouse. 
If the file is released over a window that is registered with the Workspace Manager, the 
application for that window will receive an iconEnterediat... message, filename is the 
complete name (including path) of the file to be dragged. If there is more than one file 
to be dragged, you must separate the filenames with a single tab (‘\t’) character, rect 
describes the position of the icon in the View’s coordinates, and the width and height 
of rect must both be 48.0. aFlag indicates whether the icon should slide back to its 
position in the View if the file is not accepted. If aFlag is YES and filename is not 
accepted and the user has not disabled icon animation, the icon will slide back; 
otherwise it will not. event describes where the mouse-down event occurred. 

This method returns self if the View successfully sent the file dragging message to the 
Workspace Manager; otherwise it returns nil. 

See also: - mouseDown: (Responder), 

- iconEntered: at:: icon Window: iconX: icon Y:icon Width: iconHeight: pa th List: 
(Listener), - registerWindow:toPort: (Speaker) 
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drawInSuperview 

- drawInSuperview 

Makes the View’s coordinate system identical to that of its superview. This can reduce 
the amount of PostScript code that’s generated to focus on the View. After invoking 
this method, the View’s bounds rectangle origin is the same as its frame rectangle 
origin. 

Although the View’s superview may be flipped, the View’s coordinate system won’t be 
flipped unless it receives a setFlipped: message. You should invoke 
drawInSuperview after creating the View and before applying any coordinate 
transformations to it. Returns self. 

See also: - setFlipped: 
drawPageBorder:: 

- drawPageBorder: (float) width :(float )height 

Allows applications that use the Application Kit pagination facility to draw additional 
marks on each logical page. This method is invoked by 

beginPageSetupRect:placement:, and the default implementation doesn’t draw 
anything. Returns self. 

drawSelf:: 

- drawSelf: (const NXRect *)rects :(int)rectCount 

Implemented by subclasses to draw the View. Each View subclass must override this 
method to draw itself within its frame rectangle. The default implementation of this 
method does nothing. 

This method is invoked by the display methods (display, display::, and display:::); 
you shouldn’t send a drawSelf:: message directly to a View. 

rects is an array of rectangles indicating the region within the View that needs to be 
drawn. rectCount indicates the number of rectangles in the rects array, which is either 
1 or 3. If rectCount is 1, then rects[ 0] specifies the region to be drawn. If rectCount is 
3, then rects[ 0] contains the smallest rectangle that completely encloses rects\\ \ and 
rects[ 2], the two rectangles that actually specify the regions that need to be drawn. Note 
that if rectCount is 3, you can just draw the contents of rects[ 0], or you can draw the 
contents of both rects[ 1] and rects[ 2], but there is no need to draw all three rectangles. 
For optimum drawing performance, you shouldn’t draw anything that doesn’t intersect 
with the rects rectangles, although it is possible to draw the entire contents of the View 
and simply allow the contents of the View to be clipped. 

Your implementation of drawSelf:: doesn’t need to invoke lockFocus; focus is already 
locked on an object when it’s told to draw itself. Returns self. 

See also: - display, - display::, - display::: 
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drawSheetBorder:: 


- drawSheetBorder:(float)wzVM :(floa.i)height 

Allows applications that use the Application Kit pagination facility to draw additional 
marks on each printed sheet. This method is invoked by 
beginPageSetupRect:placement:, and the default implementation doesn’t draw 
anything. Returns self. 

endHeaderComments 

- endHeaderComments 

Writes out the end of a conforming PostScript header. It prints out the 
%%EndComments line and then the start of the prologue, including the Application 
Kit’s standard printing package. The prologue should contain definitions global to a 
print job. This method is invoked by printPSCode: and faxPSCode: after 
beginPrologueBBox:creationDate:createdBy:fonts:forWhom:pages:titIe: and 
before endPrologue. Returns self. 

endPage 

- endPage 

Writes the end of a conforming PostScript page. This method is invoked after each 
page is printed. It performs an unlockFocus to balance the lockFocus done in 
beginPageSetupRect:placement:. It also generates a PostScript showpage and a 
restore. Returns self. 

See also: - beginPageSetupRect:placement: 

endPageSetup 

- endPageSetup 

Writes the end of the page setup section, which begins with a %%EndPageSetup 
comment. This method is invoked by printPSCode: and faxPSCode: just after 
beginPageSetupRect:placement: is invoked. Returns self. 
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endPrologue 
- endPrologue 

Writes out the end of the conforming PostScript prologue. This method is invoked by 
printPSCode: and faxPSCode: after the prologue of the document has been written. 
Applications can override this method to add their own definitions to the prologue. For 
example: 


- endPrologue 
{ 

DPSPrintf(DPSGetCurrentContext(), "/littleProc {pop} def"); 
return [super endPrologue]; 

} 

endPSOutput 

- endPSOutput 

Ends a print job. This method is invoked by printPSCode: and faxPSCode:. It closes 
the spool file (if any), and restores the old PostScript context so that further PostScript 
output is directed to the Window Server. Returns self. 

See also: - beginPSOutput 

endSetup 

- endSetup 

Writes out the end of the setup section, which begins with a %%EndSetup comment. 
This method is invoked by printPSCode: and faxPSCode: just after beginSetup is 
invoked. Returns self. 

endTrailer 

- endTrailer 

Writes the end of the conforming PostScript trailer. This method is invoked by 
printPSCode: and faxPSCode: just after beginTrailer is invoked. Returns self. 

See also: - beginTrailer 
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faxPSCode: 


- faxPSCode:smier 

Prints the View and all its subviews to a fax modem. If the user cancels the job, or if 
there are any errors in generating the PostScript, this method returns nil; otherwise it 
returns self. 

This method normally brings up the Fax panel before actually initiating printing, but if 
sender implements a shouldRunPrintPanel: method, the View will invoke that 
method to query sender. If sender then returns NO, then the Fax panel won’t be 
displayed, and the View will be printed using the last settings of the Fax panel. 

See also: - printPSCode:, - shouldRunPrintPanel: (Object methods) 

find Ancestor Shared With: 

- findAncestorSharedWith :aView 

Returns the closest common ancestor in the View hierarchy shared by aView and the 
receiving View, or nil if there’s no such ancestor. If aView and the receiving View are 
identical, this method returns self. 

See also: - isDescendantOf: 

findViewWithTag: 

- findViewWithTag: (mt)aTag 

Finds a descendant View of the receiving View with a tag of aTag. Returns self if the 
receiving View’s tag is aTag. Otherwise this method recursively looks at the tag of the 
View’s first subview, the first subview’s descendants, the View’s second subview, and 
so forth. This method returns the first View with matching tag, or nil if no subview or 
descendant of a subview of the receiving View has a matching tag. 

See also: - tag 

frameAngle 

- (float)frameAngle 

Returns the angle of the View’s frame relative to its superview’s coordinate system. 
See also: - rotateTo:, - rotateBy: 
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free 


- free 

Releases the storage for the View and all its subviews. This method also invalidates the 
cursor rectangles for the View’s window, frees the View’s graphics state object (if any), 
and removes the View from the view hierarchy; the View will no longer be registered 
as a subview of any other View. 

See also: - allocFromZone: (Object), - initFrame: 

freeGState 

- freeGState 

Frees the graphics state object that was previously allocated for the View. Returns self. 
See also: - allocateGState: 

getBounds: 

- getBounds :(NXRect *)theRect 

Copies the View’s bounds rectangle into the structure specified by theRect. Returns 
self. 

See also: - bounds Angle 
getFrame: 

- getFrame :(NXRect *)theRect 

Copies the View’s frame rectangle into the structure specified by theRect. The frame 
rectangle is specified in the coordinate system of the View’s superview. Returns self. 

getRect:forPage: 

- (BOOL)getRect:(NXRect *)theRect forPage:(int )page 

Implemented by subclasses to determine the rectangle of the View to be printed for 
page number page. You should override this method to fill in theRect with the 
coordinates of the View (in its own coordinate system) that represent the page 
requested. The View will later be told to display the theRect region in order to generate 
the image for this page. This method is invoked by printPSCode: and faxPSCode: if 
the View’s knowsPagesFirstdast: method returns YES. The View should not assume 
that the pages will be generated in any particular order. 

This method returns YES if page is a valid page number for the View. It returns NO if 
page is outside the View. 

See also: - knowsPagesFirstdast: 
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getVisibleRect: 

- (BOOL)getVisibleRect:(NXRect *)theRect 

Gets the visible portion of the View. A rectangle enclosing the visible portion is placed 
in the structure specified by theRect. This method returns YES if part of the View is 
visible, and NO if none of it is. 

Visibility is determined by intersecting the View’s frame rectangle against the frame 
rectangles of each of its ancestors in the view hierarchy, after appropriate coordinate 
transformations. Only those portions of the View that lie within the frame rectangles 
of all its ancestors can be visible. 

If the View is in an off-screen window, or is covered by another window, this method 
may nevertheless return YES. This method does not take into account any siblings of 
the receiving View or siblings of its ancestors. 

If the View is being printed, this method places the portion of the View that is visible 
on the page being imaged in the structure specified by theRect. 

See also: - is Visible (Window), - getDocVisibleRect: (Scroll View), 

- getDocVisibleRect: (ClipView) 

gState 

- (int)gState 

Returns the graphics state object allocated to the View. If no graphics state object has 
been allocated, or if the View has not been focused on since receiving the 
allocateGState message, this method will return 0. Graphics state objects are not 
immediately allocated by invoking the allocateGState method, but are done in a “lazy” 
fashion upon subsequent focusing. 

See also: - allocateGState, - lockFocus 

height Adj ustLimit 

- (float)height Adj ustLimit 

Returns the fraction (between 0.0 and 1.0) of the page that can be pushed onto the next 
page during automatic pagination to prevent items from being cut in half. This limit 
applies to vertical pagination. This method is invoked by printPSCode: and 
faxPSCode:. By default, this method returns 0.2. 

See also: - adjustPageHeightNew:top:bottom:limit: 
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hitTest: 


- hitTest :(NXPoint *)aPoint 

Returns the subview of the receiving View that contains the point specified by aPoint. 
The lowest subview in the View hierarchy is returned. Returns the View if it contains 
the point but none of its subviews do, or nil if the point isn’t located within the receiving 
View. 

This method is used primarily by a Window to determine which View in the View 
hierarchy should receive a mouse-down event. You’d rarely have reason to invoke this 
method, but you might want to override it to have a View trap mouse-down events 
before they get to its subviews. 

aPoint is in the receiving View’s superview’s coordinates. 


init 

- init 

Initializes the View, which must be a newly allocated View instance. This method does 
not alter the default frame rectangle, which is all zeros. This method is equivalent to 
initFrame:NULL. Note that if you instantiate a custom View from Interface Builder, 
it will be initialized with the initFrame: method; initialization code in the init method 
will not be performed. Returns self. 

See also: - initFrame: 
initFrame: 

- initFrame: (const NXRect *)frameRect 

Initializes the View, which must be a newly allocated View instance. The View’s frame 
rectangle is made equivalent to that pointed to by frameRect. This method is the 
designated initializer for the View class, and can be used to initialize a View allocated 
from your own zone. Programs generally use instances of View subclasses rather than 
direct instances of the View class. Returns self. 

See also: - init, + alloc (Object), + allocFromZone: (Object), + new (Object) 

initGState 

- initGState 

Implemented by subclasses of View to initialize the View’s graphics state. The View 
will receive this message if you previously sent it a notifyToInitGState: YES message. 
By default this method simply returns self, but you can override it to send PostScript 
code to initialize the View’s graphics state. You could use this method to set a default 
font or line width for the View. You should not use this method to send any coordinate 
transformations or clipping operators. 

See also: - allocateGState, - gState, - notifyToInitGState: 
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invalidate:: 

- invalidate: (const NXRect *)rects :(int )rectCount 

Invalidates the View and its subviews for later display. This message is sent to the View 
after scrolling if the View is a subview of a Clip View and the View’s parent Clip View 
previously received a setDisplayOnScroIl:NO message. You can override this method 
to optimize drawing performance by accumulating the invalid areas for later display. 
rects is an array of rectangles in the receiving View’s coordinate system, and rectCount 
is the number of valid rectangles in rects. 

If rectCount is 1, rects[ 0] specifies the region requiring redisplay. If rectCount is 
greater than 1, then rects[0] contains the smallest rectangle that completely encloses the 
remaining rectangles in the rects array, which specify the actual regions requiring 
redisplay. Returns self. 

See also: - rawScroll: (ClipView), - display, - display::, - display:::, - drawSelf::, 

- setDisplayOnScroll: (ClipView) 

isAutodisplay 

- (BOOL)isAutodisplay 

This method returns the View’s automatic display status. After you change your data 
in such a way that it is no longer accurately represented, you should invoke this method 
to test the View’s automatic display status. If automatic display is enabled, you should 
send a display message to the View; otherwise you should send it a 
setNeedsDisplay:YES message. 

See also: - update, - display, - set Autodisplay, - needsDisplay, 

- setNeedsDisplay:, - displayIfNeeded 

isDescendantOf: 

- (BOOL)isDescendantOf:#V7ew 

Returns YES if aView is an ancestor of the receiving View in the view hierarchy or if 
it’s identical to the receiving View. Otherwise, this method returns NO. 

See also: - superview, - subviews, - findAncestorSharedWith: 

isFlipped 

- (BOOL)isFlipped 

Returns YES if the receiver uses flipped drawing coordinates or NO if it uses native 
PostScript coordinates. By default. Views are not flipped. 

See also: - setFlipped: 
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isFocusView 


- (BOOL)isFocusView 

Returns YES if the receiving View is the View that’s currently focused for drawing; 
otherwise returns NO. In other words, returns YES if drawing commands will be 
drawn into this View. 

See also: - lockFocus 

isOpaque 

- (BOOL)isOpaque 

Returns whether the View is opaque. Returns YES if the View guarantees that it will 
completely cover the area within its frame when it draws itself; otherwise returns NO. 
This state is useful to ensure correct drawing of invalidated areas. 

See also: - setOpaque:, - opaque Ancestor, - displayFromOpaqueAncestor::: 

isRotatedFromBase 

- (BOOL)isRotatedFromBase 

Returns YES if the receiving View or any of its ancestors in the View hierarchy have 
been rotated; otherwise returns NO. 

isRotatedOrScaledFromBase 

- (B OOL)isRotatedOrScaledFromBase 

Returns YES if the receiving View or any of its ancestors in the View hierarchy have 
been rotated or scaled; otherwise returns NO. 

knowsPagesFirstilast: 

- (BOOL)knowsPagesFirst:(int *)firstPageNum last:(int *)lastPageNum 

Indicates whether this View can return a rectangle specifying the region that must be 
displayed to print a specific page. This method is invoked by printPSCode: and 
faxPSCode:. Just before invoking this method, the first page to be printed is set to 1, 
and the last page to be printed is set to the maximum integer size. You can therefore 
override this method to change the first page to be printed, and also the last page to be 
printed if the View knows where its pages lie. If this method returns YES, the printing 
mechanism will later query the View for the rectangle corresponding to a specific page 
using getRectiforPage:. 

See also: - getRectiforPage; 
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lockFocus 

- (BOOL)lockFocus 

Locks the PostScript focus on the View so that subsequent graphics commands are 
applied to the View. This method ensures that the View draws in the correct coordinates 
and to the correct device. You must send this message to the View before you draw to 
it, and you must balance it with an unlockFocus message to the View when you finish 
drawing. Returns YES if the focus was already locked on the View, and NO if it wasn’t. 

lockFocus and unlockFocus are sent for you when you display the View with one of 
the display methods; you don’t have to include lockFocus or unlockFocus in your 
drawSelf:: method. 

See also: - display:::, - isFocusView, - unlockFocus 
mouse:inRect: 

- (BOOL)mouse:(NXPoint *)aPoint inRect:(NXRect *)aRect 

Returns whether the cursor hot spot at the point specified by aPoint lies inside the 
rectangle specified by aRect. To test if the cursor lies within a specific rectangle, you 
should use this method rather than using the NXPointInRect() function; Cursor events 
are specified by the coordinates corresponding to the top left comer of the pixel under 
the cursor, so NXPointlnRectQ may return the wrong result. aPoint and aRect must 
be expressed in the same coordinate system. 

See also: - convertPoint: from View:, NXMouseInRect(), NXPointInRect() 
moveBy:: 

- moveBy :(NXCoord)deltaX :(NXCoor6.)deltaY 

Moves the origin of the View’s frame rectangle by ( deltaX , deltaY) in its superview’s 
coordinates. This method works through the moveTo:: method. Returns self. 

See also: - moveTo::, - sizeBy:: 
moveTo:: 

- moveTo :(NXCoord)* :(NXCoord)y 

Moves the origin of the View’s frame rectangle to {x, y) in its superview’s coordinates. 
This method may also send a descendantFrameChanged: message to the View’s 
superview. Returns self. 

See also: - setFrame:, - sizeTo::, - descendantFrameChanged: 
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needsDisplay 

- (BOOL)needsDisplay 

Returns whether the View needs to be displayed to reflect changes to its contents. If 
automatic display is disabled, the View will not redisplay itself automatically, so you 
can invoke this method to determine whether you need to send a display message to the 
View. The flag indicating that the View needs to be displayed is cleared by the display 
methods when the View is displayed. 

See also: - setNeedsDisplay:, - update, - setAutodisplay, - isAutodisplay, 

- display, - displaylfNeeded 

notify Ancestor WhenFr ameChanged: 

- notify Ancestor WhenFrameChanged:(BOOL)/fag 

Determines whether the receiving View will inform its ancestors in the view hierarchy 
whenever its frame changes. If flag is YES, subsequent sizeTo:: and moveTo:: 
messages to the View will send a descendantFrameChanged: message up the view 
hierarchy. If flag is NO, no descendantFrameChanged: message will be sent to the 
View’s ancestors. The descendantFrameChanged: message permits Views to make 
any necessary adjustments when a subview is resized or moved. Returns self. 

See also: - descendantFrameChanged:, - sizeTo::, - moveTo:: 

notifyToInitGState: 

- notifyToInitGState :(BOOlflflag 

Determines whether the View will be sent initGState messages to allow it to initialize 
new graphics state objects. If flag is YES, initGState messages will be sent to the View 
at the appropriate time; otherwise, they will not. By default, the View is not sent 
messages to initialize its graphics state objects. Returns self. 

See also: - initGState 

notify WhenFlipped: 

- notifyWhenFlipped:(BOOL)//tfg 

Determines whether the receiving View will inform its ancestors in the View hierarchy 
whenever its coordinate system is flipped. If flag is YES, a setFlipped: message to the 
View will send a descendantFlipped: message up the View hierarchy. If flag is NO, 
no descendantFlipped: message will be sent to the View’s ancestors. The 
descendantFlipped: message permits Views to make any necessary adjustments when 
the orientation of a subview’s coordinate system is flipped. Returns self. 

See also: - descendantFlipped:, - setFlipped: 
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opaqueAncestor 

- opaqueAncestor 

Returns the closest ancestor to the receiving View that is an opaque View. This method 
will return the receiving View if it is opaque. 

See also: - isOpaque, - displayFromOpaqueAncestor::: 

openSpooIFile: 

- openSpoolFile:(char *)filename 

Opens the filename file for print spooling. This method is invoked by printPSCode: 
and faxPSCode:; it shouldn't be directly invoked in program code. However, you can 
override it to modify its behavior. 

If filename is NULL or an empty string (filenamefO] is v \0'), the PostScript code is sent 
directly to the printing daemon, npd, without opening a file. (However, if the Window 
is being previewed or saved, a default file is opened in /tmp). 

If filename is provided, the file is opened. The printing machinery will then write the 
PostScript code to that file and the file will be printed (or faxed) using Ipr. 

This method opens a Display PostScript context that will write to the spool file, and sets 
the context of the application’s global Printlnfo object to this new context. It returns 
nil if the file can't be opened; otherwise it returns self. 

per for mKeyEqui valent: 

- (BOOL)performKeyEquivalent:(NXEvent *)theEvent 

Implemented by subclasses of View to allow them to respond to keyboard input. If the 
View responds to the key, it should take the appropriate action and return YES. 
Otherwise, it should return the result of passing the message along to super, which will 
pass the message down the View hierarchy: 


return [super performKeyEquivalent:theEvent]; 


This method returns YES if the View or any of its subviews responds to the key; 
otherwise it returns NO. 

The default implementation of this method simply passes the message down the View 
hierarchy and returns NO if none of the View’s subviews responds to the key. theEvent 
points to the event record of a key-down event. 

See also: - commandKey: (Window and Panel) 
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placePrintRect:offset: 

- placePrintRect:(const NXRect *)aRect offset:(NXPoint *) location 

Determines the location of the rectangle being printed on the physical page. This 
method is invoked by printPSCode: and faxPSCode:. aRect is the rectangle being 
printed on the current page. This method sets location to be the offset of the rectangle 
from the lower left comer of the page. All coordinates are in the default PostScript 
coordinate system of the page. 

By default, if the flags for centering are YES in the global Printlnfo object, this routine 
centers the rectangle within the margins. If the flags are NO, it defaults to abutting the 
rectangle against the top left margin. Returns self. 

printPSCode: 

- printPSCode :sender 

Prints the View and all its subviews. If the user cancels the job, or if there are any errors 
in generating the PostScript code, this method returns nil; otherwise it returns self. 

This method normally brings up the PrintPanel before actually initiating printing, but 
if sender implements a shouldRunPrintPanel: method, the View will invoke that 
method to query sender. If sender's shouldRunPrintPanel: method then returns NO, 
then the PrintPanel will not be brought up as part of the printing process, and the View 
will be printed using the last settings of the PrintPanel. 

See also: - faxPSCode:, - copyPSCodeInside:to:, - shouldRunPrintPanel: (Object 
methods) 

read: 

- read:(NXTypedStream *)stream 

Reads the View and its subviews from the typed stream stream. Returns self. 

removeCursorRect:cursor: 

- removeCursorRect:(const NXRect *)aRect cursor :anObj 

Removes a cursor rectangle from a window. aRect is given in the View’s coordinates, 
and anObj is the Cursor object for aRect. You rarely need to use this method; it’s 
usually easier to use Window’s invalidateCursorRectsForView: method and let the 
resetCursorRects mechanism restore the cursor rectangles. Returns self. 

See also: - invalidateCursorRectsForView: (Window), - resetCursorRects 


Application Kit Classes: View 2-669 



removeFromSuperview 

- removeFromSuperview 

Unlinks the View from its superview and its Window, removes it from the responder 
chain, and invalidates its cursor rectangles. Returns self. 

See also: - addSubview: 

renewGState 

- renewGState 

Forces the View to reinitialize its graphics state object. This method is lazy; the 
graphics state object is not refreshed until the View actually draws. Returns self. 

replaceSub view: with: 

- replaceSubview:o/<il//ew with inewView 

Replace oldView with newView in the View’s sub view list. This method does nothing 
and returns nil if oldView is not a subview of the View or if newView is not a View. 
Otherwise, this method returns oldView. 

See also: -addSubview: 

resetCursorRects 

- resetCursorRects 

Implemented by subclasses to reset the View’s cursor rectangles. You never send this 
message, but this method must be overridden by any View that wants cursor rectangles. 
When the Application object determines that the key window has invalid cursor 
rectangles, it sends the resetCursorRects message to the key window. The key 
window then sends the resetCursorRects message to each of its subviews. Each View 
must then send the addCursorRectrcursor: message to itself for each visible cursor 
rectangle. The View must clip the cursor rectangle against the visible rectangle, so your 
override of this method might look something like this: 

- resetCursorRects 
{ 

NXRect visible; 

if ([self getVisibleRect:&visible]) { 

[self addCursorRect:Svisible cursor:theCursor]; 

} 

return self; 

} 

See also: - invalidateCursorRectsForView: (Window), - getVisibleRect:, 

- addCursorRect:, NXIntersectionRectQ 
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resizeSubviews: 


- resizeSubviews: (const NXSize *)oldSize 

Informs the View’s subviews that the View’s bounds rectangle size has changed. This 
method is invoked from the sizeTo:: method if the View has subviews and has received 
a setAutoresizeSubviews: YES message. By default, this method sends a 
superviewSizeChanged: message to each subview. You should not invoke this method 
directly, but you may want to override it to define a specific retiling behavior. oldSize 
is the previous bounds rectangle size. Returns self. 

See also: - sizeTo::, - setAutoresizeSubviews:, - superviewSizeChanged: 
rotate: 

- rotate :(NXCoord)angle 

Rotates the View’s drawing coordinates by angle degrees from its current angle of 
orientation. Positive values indicate counterclockwise rotation; negative values 
indicate clockwise rotation. The position of the coordinate origin, (0.0, 0.0), remains 
unchanged; it’s at the center of the rotation. Returns self. 

See also: - translate::, - scale::, - setDrawRotation: 
rotateBy: 

- rotateBy :(NXCoord )deltaAngle 

Rotates the View’s frame rectangle by deltaAngle degrees from its current angle of 
orientation. Positive values rotate the frame in a counterclockwise direction; negative 
values rotate it clockwise. The position of the frame rectangle origin remains 
unchanged; it’s at the center of the rotation. Returns self. 

See also: - rotateTo: 

rotateTo: 

- rotateTo :(NXCoord)a«g/e 

Rotates the View’s frame rectangle to angle degrees in its superview’s coordinate 
system. The position of the frame rectangle origin remains unchanged; it’s at the center 
of the rotation. Returns self. 

See also: - rotateBy: 
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scale:: 


- scale: (NXCoord)x :(NXCoord)y 

Scales the View’s coordinate system. The length of units along its x and y axes will be 
equal to x and y in the View’s current coordinate system. Returns self. 

See also: - setDrawSize::, - translate::, - rotate: 
scrollPoint: 

- scrollPoint: (const NXPoint *)aPoint 

Scrolls the View, which must be a Clip View’s document view. aPoint is given in the 
receiving View’s coordinates. After the scroll, aPoint will be coincident with the 
bounds rectangle origin of the Clip View, which is its lower left comer, or its upper left 
comer if the receiving View is flipped. Returns self. 

See also: - setDocView: (ClipView) 

scrollRect:by: 

- scrollRect: (const NXRect *)aRect by:(const NXPoint *)delta 

Scrolls the aRect rectangle, which is expressed in the View’s drawing coordinates, by 
delta. Only those bits which are visible before and after scrolling are moved. This 
method works for all Views and does not require that the View’s immediate ancestor be 
a Clip View or ScrollView. Returns self. 

scrollRectToVisible: 

- scrollRectToVisible: (const NXRect *)aRect 

Scrolls aRect so that it becomes visible within the View’s parent Clip View. The 
receiving View must be a Clip View’s document view. This method will scroll the 
Clip View the minimum amount necessary to make aRect visible. aRect is a rectangle 
in the receiving View’s coordinates. Returns self if scrolling actually occurs; otherwise 
returns nil. 

See also: - setDocView: (ClipView) 

set Autodisplay: 

- setAutodisplay:(BOOL)/7tfg 

Enables or disables automatic display of the View. If/7 ag is YES, subsequent messages 
to the View that would affect its appearance are automatically reflected on the screen. 
If flag is NO, you must explicitly send a display message to reflect changes to the View. 
By default, changes are automatically displayed. If automatic display is disabled, the 
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View will set a dirty flag which you can query with the needsDisplay method to 
determine whether you need to send the View a display message. Returns self. 

See also: - isAutodisplay, - needsDisplay, - setNeedsDisplay:, - display, - update, 

- displaylfNeeded 

setAutoresizeSubviews: 

- setAutoresizeSubviews : ( BOOL)flag 

Determines whether the resizeSubviews: message will be sent to the View upon receipt 
of a sizeTo:: message. By default, automatic resizing of subviews is disabled. Returns 
self. 

See also: - resizeSubviews:, - sizeTo::, - superviewSizeChanged: 


set Autosizing: 

- set Autosizing: (unsigned int )mask 


Determines how the receiving View’s frame rectangle will change when its superview’s 
size changes. Create mask by ORing the following together: 


Flag 


Meaning 


NX_NOTSIZABLE 

NX_MINXMARGINSIZABLE 

NX_WIDTHSIZABLE 

NX_MAXXMARGINSIZABLE 

NX_MIN YMARGINSIZ ABLE 

NX_HEIGHTSIZABLE 

NX_MAXYMARGINSIZABLE 


The View does not resize with its superview. 
The left margin between Views can stretch. 
The View’s width can stretch. 

The right margin between Views can stretch. 
The top margin between Views can stretch. 

The View’s height can stretch. 

The bottom margin between Views can stretch. 


Returns self. 


See also: - sizeTo::, - resizeSubviews:, - setAutoresizeSubviews: 


setClipping: 

- setClipping:(BOOL)/?< 2 g 

Determines whether drawing is clipped to the View’s frame rectangle. Views are 
clipped by default. When you know the View won’t draw outside its frame, you can 
turn off clipping to reduce the amount of PostScript code sent to the Window Server. 
You can also use this method to enable clipping in a View that inherits from a subclass 
that disables clipping. You should send a setClipping: message to the View before it 
first draws, usually from the method that initializes the View. Returns self. 

See also: - lockFocus, - drawInSuperview, - initFrame:, - doesClip 
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setDrawOrigin:: 

- setDrawOrigin :(NXCoord)x :(NXCoord)y 

Translates the View’s drawing coordinates so that (x, y ) corresponds to the same point 
as the View’s frame rectangle origin. If the View’s drawing coordinates have been 
rotated or flipped, this won’t necessarily coincide with its bounds rectangle origin. 
Returns self. 

See also: - translate::, - setDrawSize::, - setDrawRotation: 

setDr awRotation: 

- setDrawRotation :(NXCoord)tf/zg/e 

Rotates the View’s drawing coordinates around its frame rectangle origin so that angle 
defines the relationship between the View’s frame rectangle and its drawing 
coordinates. Returns self. 

See also: - rotate:, - setDrawOrigin::, - setDrawSize:: 
setDrawSize:: 

- setDrawSize :(NXCoord)vmM : (NXCoord) height 

Scales the View’s drawing coordinates so that width and height define the size of the 
View’s frame rectangle in drawing coordinates. If the View’s drawing coordinates have 
been rotated, the View’s frame rectangle size won’t necessarily be the same as its 
bounds rectangle size. Returns self. 

See also: - scale::, - setDrawOrigin::, - setDrawRotation: 
setFIipped: 

- setFIipped:(BOOL)/fag 

Flips the direction of the View’s y coordinate. If flag is YES, the View’s origin will be 
located at its upper left comer, and coordinate values will increase towards the bottom 
of the View. You should send a setFIipped: message to a View only once, before it 
draws, usually from the method that initializes it. 

Although a View is positioned in its superview’s coordinate system, no View will have 
a flipped coordinate system unless it receives a setFlipped:YES message of its own; it 
can’t inherit flipped coordinates from its superview. 

This method may also send a descendantFIipped: message to the receiving View’s 
superview. Returns self. 

See also: - notifyWhenFlipped:, - descendantFIipped:, - initFrame:, - isFlipped 
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setFrame: 


- setFrame: (const NXRect *)frameRect 

Repositions and resizes the View within its superview’s coordinate system by assigning 
it the frame rectangle specified by frameRect. Returns self. 

See also: - initFrame:, - sizeTo::, - moveTo:: 

setNeedsDisplay: 

- setNeedsDisplay:(BOOL]/fag 

This method sets a flag indicating whether the View needs to be displayed. After the 
View changes its internal state in such a way that it’s no longer accurately reflected on 
the screen, it should query itself with an isAutodisplay message. If automatic display 
is enabled, the View should send a display message to itself. If automatic display is 
disabled, the View should send a setNeedsDisplayrYES message to itself. This 
message has no effect if automatic display is enabled. Returns self. 

See also: - update, - setAutodisplay, - isAutodisplay, - needsDisplay:, 

- display:::, - displayIfNeeded 

setOpaque: 

- setOpaque: (BOOL)flag 

✓ 

Registers whether the View is opaque. If the View guarantees it will cover the entire 
area within its frame when it displays itself, it should send itself a setOpaque: YES 
message. This method is used to ensure correct drawing of invalidated Views. Returns 
self. 

See also: - isOpaque, - opaque Ancestor, - displayFromOpaque Ancestor::: 

shouldDrawColor 

- (BOOL)shouldDrawColor 

Returns whether the View should be drawn using color. If the View is being drawn to 
a window and the window can’t store color, this method returns NO; otherwise it 
returns YES. 


sizeBy:: 

- sizeBy :(NXCoord)<ie/taM<it/z :(NXCoord )deltaHeight 

Resizes the View by deltaWidth and deltaHeight in its superview’s coordinates. This 
method works by invoking the sizeTo:: method. Returns self. 

See also: - sizeTo::, - moveBy:: 
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sizeTo:: 

- sizeTo :(NXCoord)width :(NXCoord )height 

Resizes the View’s frame rectangle to the specified width and height in its superview’s 
coordinates. It may also initiate a descendantFrameChanged: message to the View’s 
superview. Returns self. 

See also: - setFrame:, - moveTo::, - sizeBy::, - descendantFrameChanged: 
spooIFile: 

- spooIFile :(const char *) filename 

Spools the generated PostScript file to the printer. This method is invoked by 
printPSCode: and faxPSCode:. Returns self. 

subviews 

- subviews 

Returns the List object that contains the receiving View’s subviews. You can use this 
List to send messages to each View in the View hierarchy. You must not modify this 
List directly; use addSubview: and removeFromSuperview to add and remove Views 
from the View hierarchy. 

See also: - superview, - addSubview:, - removeFromSuperview 

superview 

- superview 

Returns the receiving View’s superview. 

See also: - window, - subviews, - addSubview:, - removeFromSuperview 

superviewSizeChanged: 

- superviewSizeChanged:(const NXSize *)oldSize 

Informs the View that its superview’s size has changed. This method is invoked when 
the View’s superview has received a resizeSubviews: message. This method will 
automatically resize the View according to the parameters set by the setAutosizing: 
message. You may want to override this method to provide specific resizing behavior. 
oldSize is the previous bounds rectangle size of the receiving View’s superview. 
Returns self. 

See also: - resizeSubviews:, - sizeTo::, - setAutoresizeSubviews: 
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suspendNotifyAncestorWhenFrameChanged: 

- suspendXotifvAncestorWhenFrameChanged:(BOOL)j?< 2 g 

Temporarily disables or reenables the sending of descendantFrameChanged: 
messages to the View’s superview when the View is sized or moved. You must have 
previously sent the View a notifyAncestorWhenFrameChanged:YES message for 
this method to have any effect. These messages do not nest. Returns self. 

See also: - descendantFrameChanged:, - notifyAncestorWhenFrameChanged:, 

- sizeTo::, - moveTo::, 


tag 

- (int)tag 

Returns the View’s tag, a integer that you can use to identify objects in your application. 
By default, View returns (-1). You can override this method to identify certain Views. 
For example, your application could take special action when a View with a given tag 
receives a mouse event. 

See also: - find Vie wWithTag: 
translate:: 

- translate :(NXCoord)x :(NXCoord)y 

Translates the origin of the View’s coordinate system to (x, y). Returns self. 

See also: - setDrawOrigin::, - scale::, - rotate: 

unlockFocus 

- unlockFocus 

Balances an earlier lockFocus message to the same View. If the lockFocus method 
saved the previous graphics state, this method restores it. Returns self. 

See also: - lockFocus, - display::: 

update 

- update 

Invokes the proper update behavior when the contents of the View have been changed 
in such a way that they are no longer accurately represented on the screen. If automatic 
display is enabled, this method invokes display; otherwise this method sets a flag 
indicating that the View needs to be displayed. Returns self. 

See also: - setNeedsDisplay, - isAutoDisplay, - display, - displaylfNeeded 
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width AdjustLimit 

- (float)widthAdjustLimit 

Returns the fraction (between 0.0 and 1.0) of the page that can be pushed onto the next 
page during automatic pagination to prevent items from being cut in half. This limit 
applies to horizontal pagination. This method is invoked by printPSCode: and 
faxPSCode:. By default, this method returns 0.2. 

See also: - adj ustPageHeightNew: top: bottom: limit: 


window 
- window 

Returns the Window of the receiving View. 
See also: - superview 


windowChanged: 

- windo wC hanged : newWindow 


Invoked when the Window the View is in changes (usually from nil to non-nil or vice 
versa). This often happens due to a removeFromSuperview sent to the View (or some 
View higher up the hierarchy from it). This method is especially important when the 
View is the first responder in the window, in which case this method should be 
overridden to clean up any blinking carets or other first responder dependent activity 
the View engages in. Note that resignFirstResponder is NOT called when a View is 
removed from the View hierarchy (since the View does not have the opportunity to 
reject resignation of the first responder). This method is invoked before the window 
instance variable has been changed to newWindow. Returns self. 


write: 

- write: (NXTypedStream *)stream 

Writes the receiving View and its subviews to the typed stream stream. Returns self. 


METHODS IMPLEMENTED BY VIEWS THAT ACCEPT COLOR 


acceptColorratPoint: 

- acceptColor:(NXColor)c6»/or atPoint:(NXPoint *)aPoint 

Allows a View to accept a color. If your subclass of View implements this method, it 
will be invoked when the user drags a color (as from an NXColorWell) into your View. 
Colors are typically dragged using NXColorPanel’s 

dragColor:withEvent:fromView: class method. aPoint describes the point (in the 
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View s window s coordinates) to which the color should be applied; you may want to 
use convertPointifromView: to convert aPoint to the View s coordinates. Your 
implementation of the acceptColor:atPoint: method should take whatever action is 
appropriate, which may include redisplaying the View. 

See also: - acceptColonatPoint: (NXColorWell), - convertPointifromView:, 

+ dragColor:withEvent:fromView: (NXColorPanel), NXSetColorQ 


CONSTANTS AND DEFINED TYPES 

#define NX_NOTSIZABLE (0) 

#define NX_MINXMARGINSIZABLE (1) 

#define NX_WIDTHSIZABLE (2) 

#define NX_MAXXMARGINSIZABLE (4) 

#define NX_MINYMARGINSIZABLE (8) 

#define NX_HEIGHTSIZABLE (16) 

#define NX_MAXYMARGINSIZABLE (32) 

/* Are we drawing, printing, or copying PostScript to the scrap? */ 


extern short NXDrawingStatus; 

/* NXDrawingStatus values */ 

#define NX_DRAWING 1 /* we re drawing */ 

#define NX_PRINTING 2 /* we re printing */ 

#define NX_COPYING 3 /* we re copying to the scrap */ 
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Window 


INHERITS FROM Responder : Object 

DECLARED IN appkit/Window.h 

CLASS DESCRIPTION 

The Window class defines objects that manage and coordinate windows for an 
application; each object corresponds to a physical window provided by the Window 
Server. A Window object plays a central role in an application: 

• It communicates with the Window Server to create, move, resize, reorder, and free 
a window on the screen. It also responds to event messages that inform the 
application that the window has been affected by user actions. 

• It manages a hierarchy of Views that draw inside the window and handle all 
keyboard and mouse events associated with it. It determines how events are 
assigned to Views and has methods that help regulate the View display mechanism. 

• It keeps track of the current status of the window as the key window or main 
window, as well as its location, size, and other window attributes. 

• It provides a text object—a field editor —that can be assigned small-scale editing 
tasks within the window. The field editor is used by NXBrowsers, Forms, Matrices, 
and TextFields located in the Window. 

Rectangles and Views 

A Window is defined by a frame rectangle that encloses the entire window, including 
its title bar, resize bar, and border, and by a content rectangle that encloses just its 
content area. Both rectangles are specified in the screen coordinate system. 

Corresponding to these rectangles, each Window has at least two Views in its view 
hierarchy, a frame view that fills the entire frame rectangle and draws the border, title 
bar, and resize bar, and a content view that fills the content area. The frame view is the 
responsibility of the Window object and shouldn’t be altered or sent messages by 
application programs. The content view is the highest accessible View in the Window’s 
view hierarchy; other Views can be installed as its subviews but it can’t be made the 
subview of another View. 
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Event Handling 

The Application object sends mouse and keyboard events to the Window, as well as 
window-moved, window-exposed, window-resized, and screen-changed subevents of 
the kit-defined event. The Window object handles the kit-defined subevents itself, and 
distributes the keyboard and mouse events to View objects in its view hierarchy. A 
Window receives keyboard events only if it’s the key window. 

The Window keeps track of the object that was last selected to handle keyboard events 
as its first responder. The first responder is typically the View that displays the current 
selection. In addition to keyboard events, it’s sent action messages that have a 
user-selected target (a nil target in program code). Views that don’t display selectable 
or editable material—such as Buttons, Sliders, and NXSplitViews—and respond only 
to a limited set of events don’t become the first responder. Views that can display a 
selection—such as a Text object or a Matrix—are potential first responders. The 
Window continually updates the first responder in response to the user’s mouse actions. 

Delegates 

In addition to its Views and field editor, a Window can have a delegate to coordinate 
activities within the Window and, on occasion, intervene to constrain the Window in 
some way or respond to action messages the Window receives. The delegate should be 
provided with methods that can respond to any or all of the notification methods listed 
under “METHODS IMPLEMENTED BY THE DELEGATE” near the end of this class 
specification. Before sending a notification message, the Window first checks to see 
whether the delegate can respond. If not, no message is sent. There’s no need to have 
a delegate implement all the methods. 
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INSTANCE VARIABLES 


Inherited from Object 
Inherited from Responder 
Declared in Window 


frame 

contentView 

delegate 

firstResponder 


Class 

isa; 

id 

nextResponder; 

NXRect 

frame; 

id 

contentView; 

id 

delegate; 

id 

firstResponder; 

id 

lastLeftHit; 

id 

lastRightHit; 

id 

counterpart; 

id 

fieldEditor; 

int 

winEventMask; 

int 

windowNum; 

float 

backgroundGray; 

struct _wFlags{ 
unsigned int 

style:4; 

unsigned int 

backing: 2; 

unsigned int 

buttonMask:3; 

unsigned int 

visible: 1; 

unsigned int 

isMainWindow: 1; 

unsigned int 

isKeyWindow:l; 

unsigned int 

isPanekl; 

unsigned int 

hideOnDeactivate: 1; 

unsigned int 

dontFreeWhenClosed: 1; 

unsigned int 

oneShot:l; 

} 

wFlags; 

struct _wFlags2{ 
unsigned int 

deferred: 1; 

unsigned int 

docEdited:l; 

unsigned int 

dynamicDepthLimit: 1; 


} wFlags2; 


The Window’s location and size (its frame 
rectangle) in screen coordinates. 

The View that fills the content area of the 
Window. 

The object that receives notification messages 
from the Window. 

The Responder that receives keyboard events and 
untargeted action messages sent to the Window. 
The first responder is typically a View in the 
Window’s view hierarchy, the one that displays 
the current selection, and changes in response to 
mouse-down events. 
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lastLeftHit 


The last View in the Window’s view hierarchy to 
receive a left mouse-down event. 


lastRightHit 

counterpart 

fieldEditor 

winEventMask 

windowNum 

backgroundGray 
wFlags. style 

wFlags.backing 

wFlags.buttonMask 

wFlags.visible 

wFlags.isMain Window 
wFlags.isKeyWindow 
wFlags.isPanel 
wFlags.hideOnDeactivate 


The last View in the Window’s view hierarchy to 
receive a right mouse-down event. 

The id of the Window’s mini window, or, if the 
Window is a miniwindow, the id of the Window it 
stands for. Since miniwindows aren’t created 
until they’re needed, the counterpart may be nil. 
(It will also be nil if the Window is a miniworld 
icon standing for an application.) 

A place holder for a Text object that will display 
and edit text for any Controls and Cells located 
within the window. 

The events the Window can receive from the 
Window Server. 

The window number, used by the Application Kit 
to identify the window. This number isn’t the 
global number assigned by the Window Server. It 
corresponds to a user object and is therefore local 
to the Window’s context. 

The background color of the window. 

The style of window; whether it’s plain, titled, a 
mini window, or has a frame suitable for a menu. 

The type of backing for the on-screen display; 
whether the Window is retained, nonretained, or 
buffered. 

Which controls the window has (close button, 
miniaturize button, or resize bar). 

True if the window is on-screen (in the screen 
list). 

True when the window is the main window. 

True when the window is the key window. 

True if the window is a panel. 

True if the window should be removed from the 
screen when the application deactivates. 
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wFlags.dontFreeWhenClosed True if the Window is not to be freed when closed. 

wFlags.oneShot True if the Window Server should free the 

window for this object when it’s removed from 
the screen. 

wFlags2.deferred True if the Window Server shouldn’t create a 

window for this object until it’s needed. 

wFlags2.docEdited True if the close button indicates that the 

document has been edited but not saved. 

wFlags2.dynamicDepthLimit True if the window has a dynamic depth limit that 

can change to match the depth of the display 
device. 


METHOD TYPES 

Initializing a new Window instance - init 

- initContent: style:backing:buttonMask:defer: 

- initContent:style:backing:buttonMask: 

defer: screen: 

Freeing a Window object - free 

Setting up the Window - setTitle: 

- setTitleAsFilename: 

- title 

- setContentView: 

- content View 

- setBackgroundColor: 

- backgroundColor 

- setBackgroundGray: 

- backgroundGray 

- setHideOnDeactivate: 

- doesHideOnDeactivate 

- setMiniwindowIcon: 

- miniwindowlcon 

- setOneShot: 

- isOneShot 

- setFreeWhenClosed: 

- setExcludedFromWindowsMenu: 

- isExcludedFromWindowsMenu 
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Querying window attributes 

- windowNum 

- buttonMask 

- style 

- worksWhenModal 

- screen 

- bestScreen 

Window status 

- makeKey Window 

- makeKeyAndOrderFront: 

- becomeKeyWindow 

- isKeyWindow 

- resignKey Window 

- canBecomeKeyWindow 

- becomeMainWindow 

- isMainWindow 

- resignMain Window 

- canBecomeMain Window 

Rectangle support 

- getFrame: 

- getFrame:andScreen: 

+ getFrameRect:forContentRect:style: 

+ getContentRect:forFrameRect:style: 

+ minFrameWidth:forStyle:buttonMask: 

Moving and resizing the window 

- moveTo:: 

- moveTo::screen: 

- moveTopLeftTo:: 

- moveTopLeftTo:: screen: 

- dragFrom::eventNum: 

- constrainFrameRect:toScreen: 

- place Window: 

- place Window: screen: 

- place Window AndDisplay: 

- sizeWindow:: 

- center 

Reordering the window 

- makeKeyAndOrderFront: 

- orderFront: 

- orderBack: 

- orderOut: 

- orderWindow:relativeTo: 

- isVisible 

Converting coordinates 

- convertBaseToScreen: 

- convertScreenToBase: 
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Managing the display - display 

- displaylfNeeded 

- disableDisplay 

- isDisplayEnabled 

- reenableDisplay 

- flush Window 

- flushWindowIfNeeded 

- disableFlushWindow 

- reenableFlushWindow 

- display Border 

- useOptimizedDrawing: 

- update 

Window depths + defaultDepthLimit 

- setDepthLimit: 

- depthLimit 

- setDynamicDepthLimit: 

- hasDynamicDepthLimit 

- canStoreColor 

- gState 

- endEditingFor: 

- getFieldEditor.for: 

- addCursorRect: cursor: forView: 
-removeCursorRect:cursor:forView: 

- invalidateCursorRectsForView: 

- disableCursorRects 

- enableCursorRects 

- discardCursorRects 

- resetCursorRects 

Handling user actions and events - close 

- performClose: 

- miniaturize: 

- performMiniaturize: 

- deminiaturize: 

- setDocEdited: 

- isDocEdited 

- windowExposed: 

- windowMoved: 

- windowResized: 

- screenChanged: 

Setting the event mask - setEventMask: 

- addToEventMask: 

- removeFromEventMask: 

- eventMask 


Graphics state objects 
The field editor 

Cursor management 
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Aiding event handling - getMouseLocation: 

- setTrackingRect: inside: owner:tag: left:right: 

- discardTrackingRect: 

- makeFirstResponder: 

- firstResponder 

- sendEvent: 

- rightMouseDown: 

- commandKey: 

- tryToPerform: with: 

Services menu support - validRequestorForSendType:andRetumType: 

Printing - printPSCode: 

- smartPrintPSCode: 

- faxPSCode: 

- smartFaxPSCode: 

- openSpoolFile: 

- spoolFile: 

- copyPSCode!nside:to: 


Setting up pages - knowsPagesFirst:last: 

- getRect:forPage: 

- placePrintRect:offset: 

- heightAdjustLimit 

- widthAdjustLimit 

Writing conforming PostScript - beginPSOutput 

- beginPrologueB B ox: creationDate: 

createdB y: fonts: forWhom :pages: title: 

- endHeaderComments 

- endPrologue 

- beginSetup 

- endSetup 

- beginPage:label:bBox:fonts: 

- beginPageSetupRect:placement: 

- endPageSetup 

- endPage 

- beginTrailer 

- endTrailer 

- endPS Output 

Archiving - read: 

- write: 

- awake 

Assigning a delegate - setDelegate: 

- delegate 
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CLASS METHODS 


defaultDepthLimit 

+ (NXWindowDepth)defaultDepthLimit 

Returns the default depth limit for the Window. This will be the smaller of: 

• The depth of the deepest display device available to the Window Server, or 

• The depth set for the application by the NXWindowDepthLimit parameter. 

The value returned will be one of these enumerated values (defined in the header file 

appkit/graphics.h): 

NX_TwoB itGray Depth 
NX_EightB itGray Depth 
. NX_TwelveBitRGBDepth 
NX_Twenty FourB itRGB Depth 

See also: - setDepthLimit:, - setDynamicDepthLimit:, - canStoreColor 

getContentRect:forF rameRect:styIe: 

+ getContentRect:(NXRect *)content 

forFrameRect: (const NXRect *)frame 
style :(int)<xS(y/e 

Calculates the content rectangle of a window that occupies, along with its border, title 
bar, and resize bar, the frame rectangle specified by frame and has the style indicated 
by aStyle. The rectangle is returned by reference in the structure specified by content. 
Both rectangles are in screen coordinates. Returns self. 

Use this method to get a rectangle to pass to the 

initContent:style:backing:buttonMask:defer: method if you want a window 
(including its border, title bar, and resize bar) to occupy a precise area of the screen. 
Permitted values for aStyle are discussed under that method. 

See also: + getFrameRect:forContentRect:style:, 

- initContent: style: backing: button Mask: defer: 
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getFrameRect:forContentRect:styIe: 

+ getFrameRect:(NXRect *)frame 

forContentRect: (const NXRect *)content 
style :(int )aStyle 

Calculates the frame rectangle that will be occupied by a window (including its border, 
title bar, and resize bar) if it has the content rectangle specified by content and the style 
indicated by aStyle. The frame rectangle is returned by reference in the structure 
specified by frame. Both rectangles are in screen coordinates. Returns self. 

Use this method to be sure the window will fit in the space available to it. 

See also: + getContentRect:forFrameRect:style:, 

- initContent: sty le: backing: button Mask: defer: 

minF rame Width: forStyle: buttonMask: 

+ (NXCoord)minFrame Width: (const char *)aTitle 
forStyle:(int )aStyle 
buttonMask : (int )aMask 

Returns the minimum width that a Window’s frame rectangle must have for it to display 
all of aTitle, given the specified style and button mask. Permitted values for aStyle and 
aMask are discussed under initContent:sty!e:backing:buttonMask:defer:. 

See also: - initContent:sty!e:backing:buttonMask:defer: 


INSTANCE METHODS 

addCursorRect:cursor:forView: 

- addCursorRect: (const NXRect *)aRect 
cursor :anObject 
forView: :aView 

Adds the rectangle specified by aRect to the Window’s list of cursor rectangles, and 
returns self. If the rectangle can’t be added (for example, if the rectangle doesn’t lie 
within the content area of the Window), nil is returned. 

This method is invoked by View’s addCursorRect:cursor: method, which should be 
used instead of this method inside of View implementations of the resetCursorRects 
method. 

See also: - addCursorRect:cursor: (View), - resetCursorRects (View) 


2-690 Chapter 2: Class Specifications 



addT oE ventMask: 


- (int)addToEventMask:(int)«£w£'ve/t£s' 

Adds newEvents to the Window’s current event mask and returns the original event 
mask. (newEvents and the original mask are joined through the bitwise OR operator.) 

This method is typically used when an object sets up a modal event loop to respond to 
certain events. The return value should be used to restore the Window’s original event 
mask when the modal loop done. 

See also: - setEventMask:, - eventMask, - removeFromEventMask: 

awake 

- awake 

Reinitializes the Window object by having the Window Server redisplay the window 
and assign it an accurate window number. The Window then registers itself in the 
Application object’s window list. 

An awake message is automatically sent to every object after it has been read in from 
an archive file and all the objects it refers to are in a usable state. The message gives 
the object a chance to complete any initialization that read: couldn’t do. If you 
override this method in a Window subclass, the subclass method should include a 
message to incorporate this version of awake as well: 


- awake 
{ 

[super awake]; 
return self; 

} 

See also: - read: 

backgroundColor 

- (NXColor)backgroundColor 

Returns the background color of the window when it’s located on a color display 
device. The default is the color equivalent to the NX_LTGRAY gray value. 

See also: - setBackgroundColor: 
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backgroundGray 

- (float) backgroundGray 

Returns the gray displayed in the background of the Window’s content area. The 
default is NX_LTGRAY. 

See also: - setBackgroundGray: 

becomeKeyWindow 

- becomeKeyWindow 

Records the fact that the Window is now the key window, reestablishes its cursor 
rectangles, and returns self. This method passes the becomeKeyWindow message on 
to the Window’s first responder, if the first responder implements a method that can 
respond. The delegate receives a windowDidBecomeKey: notification message, if it 
can respond. 

See also: - resignKeyWindow, - becomeMainWindow, - setDelegate: 

becomeMainWindow 

- becomeMainWindow 

Records the fact that the receiving Window is now the main window, and returns self. 
This method sends the Window’s delegate a windowDidBecomeMain: message, if the 
delegate can respond. 

See also: - resignMainWindow, - becomeKeyWindow, - setDelegate: 

beginPage:label:bBox:fonts: 

- beginPage:(int )ordinalNum 

label:(const char *)aString 
bBox:(const NXRect *)pageRect 
fonts:(const char *)fontNames 

Writes a conforming PostScript page separator. This method is invoked automatically 
when printing (or faxing) the Window; it should not be used in program code. 
However, you can override it to modify the separator that it writes. 

ordinalNum specifies the position of the page in the document (from 1 through n for an 
n-page document). 

aString is a string that identifies the page according to the document’s internal 
numbering scheme. It should contain no white space characters. If aString is NULL, 
the ASCII equivalent of ordinalNum is used. 
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pageRect is a pointer to the rectangle, in the default user coordinate system, enclosing 
all marks on the page about to be printed. If pageRect is NULL, bounding box 
information for the page isn’t written. Instead, the string “(atend)” is written to indicate 
that the endPage method will write the bounding box at the end of the page description. 

fontNames is a string listing the names of the fonts used on the page. The names should 
be separated by spaces. If the fonts used are unknown before the page is printed, 
fontNames will be NULL. The endPage method will then list the fonts at the end of 
the page description. 

See also: - endPage, - printPSCode: 

beginPageSetupRect:placement: 

- beginPageSetupRect: (const NXRect *)aRect 

placement: (const NXPoint *) location 

Writes the page setup section for a given page. This method is invoked when printing 
(or faxing) the Window after the starting comments for the page have been written; it 
should not be used in program code. However, you can override it to modify the section 
that it writes. 

This method writes out the PostScript save operator and generates the initial coordinate 
transformation to prepare for printing the aRect rectangle within the Window. The save 
operation is balanced by a restore that the endPage method writes. The aRect 
rectangle is in the Window’s base coordinate system, location is the offset of the 
rectangle from the lower left comer of the physical page; it’s specified in page 
coordinates (equal to units of the base coordinate system). 

See also: - endPageSetup, - endPage, - printPSCode: 

beginPrologueBBox:creationDate:createdBy:fonts:forWhom:pages:title: 

- beginPrologueBBox:(const NXRect *)boundingBox 

creationDate: (const char *)dateCreated 
createdBy:(const char *)anApplication 
fonts:(const char *)fontNames 
forWhom:(const char *)user 
pages: (int )numPages 
title:(const char *)aTitle 

Writes the start of a conforming PostScript header. This method is invoked when 
printing (or faxing) the Window; it should not be used in program code. However, you 
can override it to modify the header it writes. 

boundingBox is a pointer to the bounding box of the document. This rectangle should 
be in the default user coordinate system (identical to the Window’s base coordinate 
system but with the origin at the lower left comer of the page). If the bounding box is 
unknown, boundingBox will be NULL. The system will then accumulate it as pages 
are printed. 
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dateCreated is an ASCII string containing a human-readable date. If it’s NULL, the 
current date is used. 

anApplication is a string containing the name of the document creator. If it’s NULL, 
the string returned by the Application object’s appName method is used. 

fontNames is a string holding the names of the fonts used in the document. Names 
should be separated by a space. If the fonts used are unknown before the document is 
printed, fontNames will be NULL. In this case, each font that there’s a findfont 
operation for will be written in the trailer. 

user is a string containing the name of the person printing the document. If it’s NULL, 
the login name of the user is used. 

numPages specifies the number of pages in the document. If unknown at the beginning 
of printing, it has a value of -1. In this case, the pages are counted as they’re generated 
and the total is written in the trailer. 

aTitle is a string specifying the title of the document. If aTitle is NULL, the Window’s 
title is used. 

See also: - endPrologue, - endHeaderComments, - printPSCode: 

beginPSOutput 

- beginPSOutput 

Performs various initializations to prepare for generating PostScript code. This method 
is invoked when printing (or faxing) the Window; it should not be used in program 
code. However, you can override it to modify or add to the initialization it does. 

This method first makes the Display PostScript context stored in the global Printlnfo 
object (the one returned by NXApp’s printlnfo method) the current context. This has 
the effect of redirecting all PostScript output from the Window Server to the spool file 
or printer. 

See also: - endPSOutput, - printPSCode: 

beginSetup 

- beginSetup 

Writes the beginning of the document setup section. This method is invoked when 
printing (or faxing) the Window; it should not be used in program code. However, you 
can override it to modify the way it writes the section. 

The document setup section is intended for general initialization code and to set up the 
output device. It follows the document prologue but precedes any pages that are to be 
printed. At the beginning of the section, this method writes a “%%BeginSetup” 
comment and a “%%PaperSize” comment declaring the type of paper being used. It 
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also writes comments after querying the Printlnfo object with isManualFeed and 
resolution messages. 


See also: - endSetup, - printPSCode: 

beginTrailer 

- beginTrailer 

Writes the start of a conforming PostScript trailer, and returns self. This method is 
invoked when printing (or faxing) the Window after all the pages have been written; it 
should not be used in program code. However, you can override it to modify the trailer 
it writes. 

See also: - endTrailer, - printPSCode: 
bestScreen 

- (const NXScreen *)bestScreen 

Returns a pointer to the deepest screen that the Window currently is on, or NULL if the 
Window is currently off-screen. A Window can be on more than one screen if the user 
drags it so that it’s displayed partly on one device and partly on another. 

See also: - screen, - color Screen (Application) 

buttonMask 

- (int)buttonMask 

Returns a mask that indicates which buttons appear in the Window’s title bar and 
whether the Window has a resize bar. You can test the return value against these 
constants: 

NX_CLOSEBUTTONMASK 

NX_RESIZEBUTTONMASK 

NX_MINIATURIZEBUTTONMASK 

See also: - initContent:sty!e:backing:buttonMask:defer: 

canBecomeKeyWindow 

- (BOOL)canBecomeKeyWindow 

Returns YES if the receiving Window can be made the key window, and NO if it can’t. 
See also: - isKeyWindow 
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canBecomeMainWindow 

- (BOOL)canBecomeMain Window 

Returns YES if the receiving Window can be made the main window, and NO if it can’t. 
A Window can become the main window if it’s in the screen list, isn’t a Panel, and 
accepts keyboard events. 

See also: - isMainWindow 

canStoreColor 

- (BOOL)canStoreColor 

Returns YES if the Window has a depth limit that would allow it to store color values, 
and NO if it doesn’t. 

See also: - depthLimit, - shouIdDrawCoIor (View) 

center 

- center 

Moves the window to the center of the screen. This is used when putting up modal 
panels by Application’s runModalFor: method. Returns self. 

close 

- close 

Removes the Window from the screen. If the Window is to be freed when it’s closed 
(the default), this method goes on to remove the Window object from the Application 
object’s list of Windows, have the Window Server destroy the window, and send the 
object a free message. 

This method is invoked by the Application Kit when the user clicks the Window’s close 
button. You should invoke it only when you have no other use for the Window (unless 
the Window is not to be freed when it’s closed). 

Returns nil. 

See also: - close (Menu), - setFreeWhenClosed: 
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commandKey: 

- (BOOL)commandKey:(NXEvent *)theEvent 

Returns NO, to indicate that no objects within the Window can handle Command 
key-down events. 

If a Window has any Views that might want to respond to the key-down event as a 
keyboard alternative, it must override this version of the method and initiate a 
performKeyEquivalent: message to the Views. For example: 


- (BOOL)commandKey:(NXEvent *)theEvent 
{ 

if ( [contentView performKeyEquivalent:theEvent] ) 

return( YES ); 

else 

return( NO ); 

} 

The Panel class implements a method like this so that the controls within a panel and 
the commands within a menu can respond to keyboard alternatives. 

A commandKey: message is initiated by the Application object when it receives a 
key-down event while the Command key is pressed. It sends the message to each 
Window in its window list, until one of them responds YES. A Window doesn’t have 
to be on-screen to receive the message. 

The argument, theEvent , is a pointer to the key-down event. 

See also: - performKeyEquivalent: (View), - commandKey: (Panel) 

constrainFrameRectrtoScreen: 

- (BOOL)constrainFrameRect:(NXRect *)theFrame 
toScreen:(NXScreen *)screen 

Modifies the frame rectangle of the Window so that enough of it will appear on the 
specified screen to give users control over the Window’s title bar. If screen is NULL, 
the Window is constrained to the nearest screen. 

A constrainFrameRect:toScreen: message is sent to a titled Window (with or without 
a resize bar) whenever it’s placed on-screen or resized by the application. The proposed 
frame rectangle for the Window is passed in the structure referred to by theRect. If this 
method modifies the rectangle, it returns YES. Otherwise, it returns NO. 

You can override this method to prevent a particular Window from being constrained 
to the screen, or to constrain it differently. 
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contentView 

- contentView 

Returns the id of the Window’s current content view. 

See also: - setContentView: 

con vertBaseToScreen: 

- convertBaseToScreen:(NXPoint *)aPoint 

Converts the point referred to by aPoint from the Window’s base coordinate system to 
the screen coordinate system, and returns seif. 

See also: - convertScreenToBase: 

con vertScreenToB ase: 

- convertScreenToBase :(NXPoint *)aPoint 

Converts the point referred to by aPoint from the screen coordinate system to the 
Window’s base coordinate system, and returns self. 

See also: - convertBaseToScreen: 
copyPSCodelnside: to: 

- copyPSCodeInside:(const NXRect *)rect to:(NXStream *)stream 

Generates PostScript code for all the Views located inside the rect portion of the 
Window. The rectangle is specified in the Window’s base coordinates. The PostScript 
code is written to stream. 

This method generates PostScript code in the same way that printPSCode: and 
faxPSCode: do, except that it writes it to stream. If an exception is raised, it doesn’t 
return. 

See also: - printPSCode:, - faxPSCode: 
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delegate 

- delegate 

Returns the Window’s delegate, or nil if it doesn’t have one. 

See also: - setDelegate: 

deminiaturize: 

- deminiaturizeisewder 

Removes the receiving miniwindow from the screen and places the real Window at the 
front of its tier. The value passed in sender is ignored. Returns self. 

See also: - miniaturize: 
depthLimit 

- (NXWindowDepth)depthLimit 

Returns the depth limit of the Window. This will be one of the following enumerated 
values (defined in the header file appkit/graphics.h): 

NXJDefaultDepth 
NX_TwoB itGray Depth 
NX_EightBitGrayDepth 
NX_TwelveB itRGBDepth 
NX_TwentyFourB itRGBDepth 

If the return value is NX_DefaultDepth, you can find out what depth that corresponds 
to by sending the Window class a defaultDepthLimit message. 

See also: + defaultDepthLimit, - setDepthLimit:, - setDynamicDepthLimit: 

disableCursorRects 

- disableCursorRects 

Disables all cursor rectangle management within the Window. Typically this method 
is used when you need to do some special cursor manipulation, and you don’t want the 
Application Kit interfering. Returns self. 

See also: - enableCursorRects 
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disableDisplay 

- disableDisplay 

Prevents the display methods defined in the View class from displaying any Views 
within the Window. This permits you to alter or update the Views before displaying 
them again. 

Displaying should be disabled only temporarily. Each disableDisplay message should 
be paired with a subsequent reenableDisplay message. Pairs of these messages can be 
nested; drawing won’t be reenabled until the last (unnested) reenableDisplay message 
is sent. 

Returns self. 

See also: - reenableDisplay, - isDisplayEnabled, - display::: (View) 

disableFlushWindow 

- disableFlushWindow 

Disables the flush Window method for the Window. If the Window is a buffered 
window, drawing won’t automatically be flushed to the screen by the display methods 
defined in the View class. This permits several Views to be displayed before the results 
are shown to the user. 

Flushing should be disabled only temporarily, while the Window’s display is being 
updated. Each disableFlushWindow message should be paired with a subsequent 
reenableFlushWindow message. Message pairs can be nested; flushing won’t be 
reenabled until the last (unnested) reenableFlushWindow message is sent. 

Returns self. 

See also: - reenableFlushWindow, - flush Window, - disableDisplay 

discardCursorRects 

- discardCursorRects 

Removes all cursor rectangles from the Window, and returns self. This method is 
invoked by resetCursorRects to clear out existing cursor rectangles before resetting 
them. In general, you wouldn’t invoke it in the code you write, but might want to 
override it to change its behavior. 

See also: - resetCursorRects 
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discardTrackingRect: 

- discardTrackingRect: ( mt)trackNum 

Removes the tracking rectangle identified by the trackNum tag through a call to 
PScleartrackingrectO, and returns seif. The tag was assigned when the tracking 
rectangle was created. 

See also: - setTrackingRect:inside:owner:tag:left:right: 

display 

- display 

Displays all drawing done within the window, including the border, resize bar, and title 
bar. Each visible View within the Window’s view hierarchy will receive a display 
message. If displaying had been disabled within the Window, this method reenables it. 
Returns self. 

See also: - display (View), - disableDisplay, - displaylfNeeded 


displayBorder 

- displayBorder 

Redraws the Window’s border, title bar, and resize bar, and returns self. This is 
normally done automatically for you. 

See also: - display 

displaylfNeeded 

- displaylfNeeded 

Descends the view hierarchy in the Window, sending a display message to each View 
that has been tagged as needing to be updated (that has its needsDisplay flag set). This 
method is useful when you want to disable displaying in the Window, modify a series 
of Views, then display only the ones that were modified. Returns self. 

See also: - display, - setNeedsDisplay: (View), - update (View) 

doesHideOnDeactivate 

- (BOOL)doesHideOnDeactivate 

Returns YES if the Window will disappear from the screen when the application is 
deactivated, and NO if it won’t. 

See also: - setHideOnDeactivate: 


Application Kit Classes: Window 2-701 



dragFrom: :eventNum: 

- dragFrom :(float)x 

:(float)y 

e ventNum : (int )num 

Lets the user drag a window from a point within its interior. By default, users can drag 
any window that has a title bar. If you want the user to be able to drag a window without 
a title bar, you can design a View that will invoke this method when it receives a 
mouse-down event. The Window Server will intercept subsequent mouse-dragged 
events, move the window to its new position, and inform the application through a 
window-moved subevent when the user releases the mouse button. 

The first two arguments, (. x , y), give the cursor’s location in base coordinates. The third 
argument, num, is the event number for the mouse-down event. All three can be taken 
directly from the event record for the mouse-down event. Returns self. 

See also: -moveTo:: 

enableCursorRects 

- enableCursorRects 

Reenables cursor rectangle management that had been disabled by the 
disableCursorRects method. Returns self. 

See also: - disableCursorRects 

endEditingFor: 

- endEditingFor:a«0&/<?ct 

Makes the Window’s field editor (a Text object) available for a new editing assignment 
by detaching it from the object it’s currently serving (normally its superview and 
delegate). If the field editor is the first responder, the Window is made the new first 
responder. This forces a textDidEndrendChar: message to be sent to the field editor’s 
delegate. The field editor then is assigned a nil delegate and is removed from the view 
hierarchy (its superview is made nil). This forces an end to editing even if the field 
editor had refused to resign its status as the first responder. 

To conditionally end editing, first try to make the Window the first responder: 

if ( [myWindow makeFirstResponder:myWindow ] ) { 

[myWindow endEditingFor:nil]; 

} 

makeFirstResponder: returns nil if the current first responder won’t resign. This is 
the preferred way to verify all fields when an OK button is pressed in a panel, for 
example. 
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Returns self. 


See also: - getFieldEditor:for: 

endHeaderComments 

- endHeaderComments 

Writes out the end of a conforming PostScript header. This method is invoked when 
printing (or faxing) the Window; it should not be invoked in program code. However, 
you can override it to modify the comments it writes or add to the beginning of the 
document prologue. The prologue contains definitions global to a print job. 

This method writes the “%%EndComments” line and then writes the Application Kit’s 
standard printing package to begin the prologue proper. If there’s an error in writing 
the package, an NX_printPackageError exception is raised and this method will not 
return. 

See also: - printPSCode:, 

- beginPrologueB Box: creationDate: createdBy: fonts: for Whom: pages: title: 

endPage 

- endPage 

Writes the end of a conforming PostScript page. This method is invoked after each 
page is written when printing (or faxing) the Window; it should not be used in program 
code. However, you can override it to modify what it writes. 

This method generates a restore operation after each page has been described and a 
showpage operation when there are no more pages to be printed on the current sheet of 
paper. 

See also: - beginPage:label:bBox:fonts:, - beginPageSetupRectiplacement:, 

- printPSCode: 

endPageSetup 

- endPageSetup 

Writes the “%%EndPageSetup” comment to end the page setup section. This method 
is invoked automatically when printing (or faxing) the Window; it should not be used 
in program code. However, you can override it to modify or add to what it writes. 

See also: - beginPageSetupReet:placement:, - printPSCode: 
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endPrologue 

- endPrologue 

Writes the end of a conforming PostScript prologue. This method is invoked when 
printing (or faxing) the Window; it should not be used in program code. However, you 
can override it to modify the end of the prologue. 

See also: - printPSCode:, 

- beginPrologueBBox: creationDate icreatedBy: fonts: for Whom: pages: title: 

endPSOutput 

- endPSOutput 

Finishes a print job by closing the spool file (if any) and restoring the display context 
so that further PostScript code will be directed to the Window Server. This method is 
invoked when printing (or faxing) the Window; it should not be used in program code. 
However, you can override it to modify its behavior. 

See also: - beginPSOutput, - printPSCode: 

endSetup 

- endSetup 

Writes the “%%EndSetup” comment that terminates the document setup section. This 
method is invoked when printing (or faxing) the Window; it should not be used in 
program code. However, you can override it to add to what it writes. 

See also: - beginSetup, - printPSCode: 

endTrailer 

- endTrailer 

Writes a PostScript conforming trailer. This method is invoked when printing (or 
faxing) the Window; it should not be used in program code. However, you can override 
it to modify or add to the trailer it writes. 

See also: - beginTVailer, - printPSCode: 

eventMask 

- (int)eventMask 

Returns the current event mask for the Window. Use this method when you need to 
know which types of events the Window Server might associate with the window and 
send to the application. 

See also: - setEventMask:, - addToEventMask:, - removeFromEventMask: 
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faxPSCode: 


- faxPSCod e:sender 

Prints the Window (all the Views in its view hierarchy including the frame view) to a 
fax modem. A return value of nil indicates that there were errors in generating the 
PostScript code or that the user canceled the job. 

In the current user interface, faxing is initiated from within the Print panel. However, 
with this method, you can provide users with an independent control for faxing a 
Window. 

This method normally brings up the Fax panel before actually beginning printing. But 
if sender implements a shouldRunPrintPanel: method, that method will be invoked 
to first query whether to run the panel. If shouldRunPrintPanel: returns NO, the Fax 
panel won’t be displayed, and the Window will be printed using the last settings of the 
panel. 

See also: - smartFaxPSCode:, - printPSCode:, - shouldRunPrintPanel: (Object 
Methods) 

firstResponder 

- firstResponder 

Returns the current first responder for the Window. 

See also: - makeFirstResponder:, - acceptsFirstResponder (Responder) 

flushWindow 

- flushWindow 

Flushes the Window’s off-screen buffer to the screen, if the receiving Window is a 
buffered window and flushing hasn’t been disabled by disableFlushWindow. This 
message is automatically invoked when you send the display message to a View. 
Returns self. 

See also: - display:: (View), - disableFlushWindow 

flushWindowIfNeeded 

- flushWindowIfNeeded 

Flushes the Window’s off-screen buffer to the screen if the receiving Window is a 
buffered window, flushing isn’t temporarily disabled, and there were some previous 
flushWindow messages that had no effect because flushing was disabled. Using this 
method after a reenableFlushWindow message, rather than using flushWindow, will 
help eliminate unnecessary calls to the Window Server. Returns self. 

See also: - flushWindow, - disableFlushWindow, - reenableFlushWindow 
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free 


- free 

Deallocates memory for the Window object, for all the objects in its view hierarchy, and 
for all its instance variables, including the field editor. 

getFieldEditorifor: 

- getFieldEditor:(BOOL)/<3g fo v:anObject 

Returns the field editor, the Text object associated with the Window. If there’s no field 
editor and flag is YES, this method creates a new Text object and assigns it to the 
fieldEditor instance variable before returning the new object’s id. If flag is NO, the 
current value of the fieldEditor instance variable is returned, even if nil. 

The fieldEditor remains nil until a Text object is created with this method. 

Before returning the field editor, this method sends the Window’s delegate a 
windowWillReturnFieldEditorrtoObject: message, giving it a chance to substitute 
another object for the field editor. If it does, the substitute will be returned instead of 
the field editor. The substitute is not assigned to the fieldEditor instance variable. 

By making the field editor a temporary subview and becoming its temporary delegate, 
Controls such as a TextField are able to use its services for entering, editing, and 
selecting text. Other Views can use it in the same way. 

See also: - endEditingFor: 
getFrame: 

- getFrame:(NXRect *)theRect 

Places the Window’s frame rectangle—its location and size in screen coordinates—in 
the rectangle specified by theRect, and returns self. 

See also: - getFrame randScreen: 
getFrame:andScreen: 

- getFrame :(NXRect *)theRect andScreen: (const NXScreen *)theScreen 

Copies the Window’s frame rectangle into the structure referred to by theRect. The 
screen where the Window is located is provided in the structure referred to by 
theScreen. The frame rectangle is specified relative to the lower left comer of the 
screen. However, if theScreen is NULL, the frame rectangle is specified in absolute 
coordinates (relative to the origin of the screen coordinate system). Returns self. 

See also: - getFrame: 
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getMouseLocation: 

- getMouseLocation: (NXPoint *)thePoint 

Places the current location of the cursor in the structure specified by thePoint. Usually, 
this information is available somewhere else, such as in the current event record. But 
when the event record isn’t recent enough or is unavailable, you can use this method to 
get the location from the Window Server. The location is provided in the Window’s 
base coordinate system. Returns self. 

See also: - currentEvent (Application) 

getRect:forPage: 

- (BOOL)getRect:(NXRect *)theRect forPage:(int)p< 2 ge 

Implemented by subclasses to provide the rectangle to be printed for page number 
page. A Window receives getRect:forPage: messages when it’s being printed (or 
faxed) if its knowsPagesFirst:last: method returns YES. 

If page is a valid page number for the Window, this method should return YES after 
providing (in the variable referred to by theRect) the rectangle that represents the page 
requested. The rectangle should be specified in the Window’s base coordinates. 

If page is not a valid page number, this method should return NO. By default, it returns 
NO. 

The Window may receive a series of getRectrforPage: messages, one for each page 
that’s being printed. It should not assume that the pages will be generated in any 
particular order. 

See also: - knowsPagesFirst:last:, - printPSCode: 

gState 

- (int)gState 

Returns the PostScript graphics state object associated with the Window. 

hasDynamicDepthLimit 

- (BOOL)hasDynamicDepthLimit 

Returns YES if the Window’s depth limit can change when it changes screens, and NO 
if it can’t. 

See also: - setDynamicDepthLimit: 
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heightAdjustLimit 

- (float)heightAdjustLimit 

Returns the fraction of a page that can be pushed onto the next page to prevent items 
from being cut in half. The limit applies to vertical pagination. By default, it’s 0.2. 

This method is invoked during automatic pagination when printing (or faxing) the 
Window; it should not be used in program code. However, you can override it to return 
a different value. The value returned should lie between 0.0 and 1.0 inclusive. 

See also: - widthAdjustLimit 


init 


- init 


Initializes the receiver, a newly allocated Window object, by passing default parameters 
to the initContent:style:backing:buttonMask:defer: method. The initialized object 
is a plain, buffered window, and has a default frame rectangle. Returns self. 

See also: - initContent:style:backing:buttonMask:defer: 

initContent:sty!e:backing:buttonMask:defer: 

- initContent:(const NXRect *)contentRect 
style:(int )aStyle 
backing: (mi)bufferingType 
buttonMask: (int )mask 
defer:(BOOL )flag 

Initializes the Window object immediately after it has been allocated by Object’s alloc 
or allocFromZone: method, and returns self. This method is the designated initializer 
for the Window class. Its five arguments specify the Window’s frame rectangle, style, 
buffering type, controls, and whether or not the Window Server will defer creating a 
window for the object until it’s needed. 

The first argument, contentRect, specifies the location and size of the Window’s content 
area in screen coordinates. If a NULL pointer is passed for this argument, a default 
rectangle is used. 
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The second argument, aStyle, specifies the window’s style. It can be: 

NX_PL AIN STYLE 
NX_TITLEDSTYLE 
NX_RESIZEBARSTYLE 
NX_MENU STYLE 
NX_MINIWINDOW STYLE 
NX_MINIWORLDSTYLE 
NX_TOKENST YLE 

However, you’d generally choose from the first three styles in this list. Menu styles are 
appropriate for windows created with methods defined in the Menu class; 
miniwindows, miniworld icons, and tokens (application icons) are created for you by 
the Application Kit. 

The third argument, bujferingType, specifies one of the three possibilities for buffering 
the drawing done in the Window: 

NX_NONRETAINED 

NX_RETAINED 

NX.BUFFERED 

The fourth argument, mask, specifies the controls in the Window’s title bar and frame. 
You build the mask by joining (with the bitwise OR operator) the individual masks for 
each type of button: 

NX_CLOSEBUTTONMASK 

NX_RESIZEBUTTONMASK 

NX_MINIATURIZEBUTTONMASK 

You can get all three controls by using the NX_ALLBUTTONS mask. Although called 
a “button,” NX_RESIZEBUTTONMASK refers to the resize bar. All Windows with a 
style of NX_RESIZEBARSTYLE must set this mask in order for the resize bar to work. 

The fifth argument, flag, determines whether or not the Window Server will create a 
window for the new object immediately. If flag is YES, it will defer creating the 
window until it is ordered on-screen. All display messages sent to the Window or its 
Views will be postponed until the window is created, just before it’s moved on-screen. 
Deferring the creation of the window improves launch time and minimizes the virtual 
memory load on the Server. 

The Window creates a direct instance of the View class to be its default content view. 
You can replace it with your own object by using the setContentView: method. 

See also: - orderFront:, - setTitle:, - setOneShot: 
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initContent: style: backing: buttonMask: defer: screen: 

- initContent: (const NXRect *)contentRect 

style:(in t)aStyle 
backing:(int)bufferingType 
buttonMask : (int )mask 
defer: {BOOL)jlag 
screen:(const NXScreen *)aScreen 

Initializes the Window object immediately after it has been allocated (by Object’s alloc 
or allocFromZone: method), and returns self. This method is equivalent to 
initContent:style:backing:buttonMask:defer:, except that the content rectangle is 
specified relative to the lower left comer of aScreen. 

If aScreen is NULL, the content rectangle is interpreted relative to the lower left comer 
of the main screen. The main screen is the one that contains the current key window, 
or, if there is no key window, the one that contains the main menu. If there’s neither a 
key window nor a main menu (if there’s no active application), the main screen is the 
one where the origin of the screen coordinate system is located. 

See also: - initContent:style:backing:buttonMask:defer: 

invalidateCursorRectsForView: 

- invalidateCursorRectsForViewiaVzcw 

Marks the Window as having invalid cursor rectangles. If the Window is the key 
window, the Application object will send it a resetCursorRects message to have it fix 
its cursor rectangles before getting the next event. If the Window isn’t the key window, 
it will receive the message when it next becomes the key window. Returns self. 

See also: - resetCursorRects 

isDisplayEnabled 

- (BOOL)isDisplayEnabled 

Returns YES if the display methods are currently able to display Views in the receiving 
Window’s view hierarchy, and NO if they’re not. 

See also: - disableDisplay, - reenableDisplay, - display::: (View) 

isDocEdited 

- (BOOL)isDocEdited 

Returns YES if the Window’s document has been edited, otherwise returns NO. 

See also: - setDocEdited: 
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isExcludedFromWindowsMenu 


- (B OOL)isExcludedFrom Windo wsMenu 

Returns YES if the Window will not be listed in the application’s Windows menu, and 
NO if it will be. 

See also: - setExcludedFromWindowsMenu: 

isKeyWindow 

- (BOOL)isKeyWindow 

Returns YES if the receiving Window is currently the key window, and NO if it isn’t. 
See also: - isMainWindow, - becomeKey Window, - resignKey Window 

isMain Window 

- (BOOL)isMainWindow 

Returns YES if the receiving Window is currently the main window, and NO if it isn’t. 
See also: - isKeyWindow, - becomeMainWindow, - resignMainWindow 

isOneShot 

- (BOOL)isOneShot 

Returns YES if the physical window that the Window object manages is freed when it’s 
removed from the screen list, and NO if not. The default is NO. 

See also: - setOneShot: 

isVisible 

- (BOOL)is Visible 

Returns YES if the Window is in the Window Server’s screen list, and NO if it’s not. 
A Window can be in the list and still not be visible, either because it’s positioned 
off-screen or because it’s covered by other Windows. In either of these cases, isVisible 
may, nevertheless, return YES. 

See also: - getVisibleRect: (View) 
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knowsPagesFirstilast: 

- (BOOL)knowsPagesFirst:(int *)firstPageNum Iast:(int *)lastPageNum 

Implemented by subclasses to indicate whether the Window knows where its own 
pages lie. This method is invoked when printing (or faxing) the Window. Although it 
can be implemented in a Window subclass, it should not be used in program code. 

If this method returns YES, the Window will receive getRectiforPage : messages 
querying it for the rectangles corresponding to specific pages. If it returns NO, 
pagination will be done automatically. By default, it returns NO. 

Just before this method is invoked, the first page to be printed is set to 1 and the last 
page to be printed is set to the maximum integer size. An implementation of this 
method can set JirstPageNum to a different initial page (for example, a chapter may start 
on page 40), even if it returns NO. If it returns YES, lastPageNum can be set to a 
different final page. If it doesn’t reset lastPageNum , the subclass implementation of 
getRect:forPage: must be able to signal that a page has been asked for beyond what is 
available in the document. 

See also: - getRect:forPage:, - printPSCode: 

makeFirstResponder: 

- makeFirstResponder:u;/?^po«<ier 

Makes aResponder the first receiver of keyboard events and action messages sent to the 
Window. If aResponder isn’t already the Window’s first responder, this method first 
sends a resignFirstResponder message to the object that currently is, and a 
becomeFirstResponder message to aResponder. However, if the old first responder 
refuses to resign, no changes are made. 

The Application Kit uses this method to alter the first responder in response to 
mouse-down events; you can also use it to explicitly set the first responder from within 
your program. aResponder should be a Responder of one type or another; it will 
usually be a View in the Window’s view hierarchy. 

If successful in making aResponder the first responder, this method returns self. If not 
(if the old first responder refuses to resign), it returns nil. 

See also: - becomeFirstResponder (Responder), - resignFirstResponder 
(Responder) 
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makeKey AndOrderF ront: 

- makeKeyAndOrderFront:s<?nd<?r 

Moves the Window to the front of the screen list and makes it the key window. This 
method can be used in action message. It’s a shorthand for: 

[receiver orderWindow:NX_ABOVE relativeTo:0]; 

[receiver makeKeyWindow]; 


Returns self. 

See also: - orderFront:, - orderBack:, - orderOut:, - orderWindow:relativeTo: 

makeKeyWindow 

- makeKeyWindow 

Makes the receiving Window object the key window, and returns self. 

See also: - becomeKeyWindow, - isKeyWindow 

miniaturize: 

- miniaturize '.sender 

Removes the Window from the screen list and displays its miniwindow counterpart 
on-screen. If the Window doesn’t have a miniwindow counterpart, one is created. 

A miniaturize: message is generated when the user clicks the miniaturize button in the 
Window’s title bar. This method has a sender argument so that it can be used in an 
action message from a Control. It ignores this argument. Returns self. 

See also: - deminiaturize: 

miniwindowlcon 

- (const char *)miniwindowIcon 

Returns the name of the icon that’s displayed on the Window’s miniwindow 
counterpart. 

See also: - setMiniwindowIcon: 
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moveTo:: 


- moveTo :(NXCoord)x :(NXCoord)y 

Repositions the Window on the screen. The arguments specify the new location of the 
window—the lower left comer of its frame rectangle—in screen coordinates. Returns 
self. 

See also: - dragFrom::eventNum:, - moveTopLeftTo:: 
moveTo: .’screen: 

- moveTo: (NXCoord)x :(NXCoord)y screen: (const NXScreen *)aScreen 

Repositions the Window so that its lower left comer lies at (*, y) relative to a coordinate 
origin at the lower left comer of aScreen. If aScreen is NULL, this method is the same 
as moveTo::. Returns self. 

moveTopLeftTo:: 

- moveTopLeftTo :(NXCoord)x :(NXCoord)y 

Repositions the Window on the screen. The arguments specify the new location of the 
Window’s top left comer—the top left comer of its frame rectangle—in screen 
coordinates. Returns self. 

See also: - dragFrom::eventNum:, - moveTo:: 
moveTopLeftTo: :screen: 

- moveTopLeftTo:(NXCoord)jc :(NXCoord)y screen:(const NXScreen *)aScreen 

Repositions the Window so that its top left comer lies at (*, y) relative to a coordinate 
origin at the lower left comer of aScreen. If aScreen is NULL, this method is the same 
as moveTopLeftTo::. Returns self. 

See also: -moveTo:: 

openSpoolFile: 

- openSpoolFile: (char *) filename 

Opens the filename file for print spooling. This method is invoked when printing (or 
faxing) the Window; it shouldn’t be used in program code. However, you can override 
it to modify its behavior. 

If filename is NULL or an empty string (filename[ 0] is ‘\0’), PostScript code for the 
Window will be sent directly to the printing daemon, npd, without opening a file. 
(However, if the Window is being previewed or saved, a default file is opened in /tmp). 
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If a filename is provided, the file is opened. The printing machinery will then write the 
PostScript code to that file and the file will be printed using lpr. 

This method opens a Display PostScript context that will write to the spool file, and sets 
the context of the global Printlnfo object to this new context. It returns nil if the file 
can’t be opened. 

See also: - printPSCode: 

orderBack: 

- orderBack '.sender 

Moves the Window to the back of its tier in the screen list. It may also change the key 
window and main window. This method is a shorthand for: 

[ receiver orderWindow:NX_BELOW relativeTo:0]; 

Returns self. 

See also: - orderFront:, - orderOut:, - orderWindow:relativeTo:, 

- makeKeyAndOrderFront: 

orderFront: 

- orderFront: sender 

Moves the Window to the front of the screen list. It may also change the key window 
and main window. This method is a shorthand for: 

[ receiver orderWindow:NX_ABOVE relativeTo:0]; 

Returns self. 

See also: - orderBack:, - orderOut:, - orderWindow:relativeTo:, 

- makeKeyAndOrderFront: 

orderOut: 

- orderOut '.sender 

Takes the Window out of the screen list. It may also change the key window and main 
window. This method is a shorthand for: 

[receiver orderWindow:NX_OUT relativeTo:0]; 

Returns self. 

See also: - orderFront:, - orderBack:, - orderWindow:relativeTo: 
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orderWindow: r elativeTo: 

- orderWindow \(ml)place relativeTo:(int)ctf/*erM« 

Repositions the window in the Window Server’s screen list, place can be one of: 

NX_ ABOVE 

nx_below 

NX_OUT 

If it’s NX_OUT, the window is removed from the screen list and otherWin is ignored. 
If it’s NX_ABOVE or NX_BELOW, otherWin is the window number of the window 
that the receiving Window is to be placed above or below. If otherWin is 0, the 
receiving Window will be placed above or below all other windows. Returns self. 

See also: - orderFront:, - orderBack:, - orderOut:, - makeKeyAndOrderFront: 


performClose: 

- performClose '.sender 

Simulates the user clicking the close button by momentarily highlighting the button 
then closing the window. Returns self. 

See also: - performClick: (Button), - close, - performMiniaturize: 

per for mMiniatur ize: 

- performMiniaturize:se«£fer 

Simulates the user clicking the miniaturize button by momentarily highlighting the 
button then miniaturizing the window. Returns self. 

See also: - performClick: (Button), - miniaturize:, - performClose: 
placePrintRectioffset: 

- placePrintRect:(const NXRect *)aRect offset:(NXPoint *) location 

Determines the location of the rectangle being printed on the physical page. This 
method is invoked when printing (or faxing) the Window; it should not be used in 
program code. However, you can override it to change the way it places the rectangle. 

aRect specifies the rectangle being printed on the current page; location is set by this 
method to be the offset of the rectangle from the lower left comer of the page. All 
coordinates are in the base coordinate system (that of the page itself). 

By default, if the flags for centering are YES in the global Printlnfo object, this method 
centers the rectangle within the margins. If the flags are NO, it abuts the rectangle 
against the top and left margins. 

See also: - getRect: for Page:, - printPSCode: 
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placeWindow: 

- placeWindow:(const NXRect *)frameRect 

Resizes the window without redrawing any of its contents, frameRect specifies a 
structure that contains the new frame rectangle of the window in screen coordinates. 
The rectangle encloses the entire window, including the border, title bar, and resize bar. 

This method allows resizing from any window comer or from any point along the 
window border, but it doesn’t move what’s displayed within the window or alter the 
origin of the base coordinate system. Returns self. 

See also: - sizeWindow::, - moveTo::, - placeWindowAndDisplay: 
place W indow: screen 

- placeWindow: (const NXRect *)frameRect screen:(const NXScreen *)aScreen 

Resizes the window, just as placeWindow: does, except that the frame rectangle is 
specified relative to a coordinate origin at the lower left comer of aScreen. If aScreen 
is NULL, this method is the same as placeWindow:. Returns self. 

See also: - placeWindow:, - placeWindowAndDisplay: 

placeWindowAndDisplay: 

- placeWindowAndDisplay: (const NXRect *)frameRect 

Resizes the window, just as placeWindow: does, but redisplays its contents before the 
resized window is shown to the user. This prevents the resized window (with unaltered 
contents) from being displayed before the Views that draw within the window are given 
a change to adjust to its new size. Returns self. 

See also: - placeWindow: 

printPSCode: 

- printPSCode '.sender 

Prints the Window (all the Views in its view hierarchy including the frame view). A 
return value of nil indicates that there were errors in generating the PostScript code or 
that the user canceled the job. 

This method normally brings up the Print panel before actually beginning printing. But 
if sender implements a shouldRunPrintPanel: method, that method will be invoked 
to first query whether to run the panel. If shouldRunPrintPanel: returns NO, the Print 
panel won’t be displayed, and the Window will be printed using the last settings of the 
panel. 

See also: - smartPrintPSCode:, - faxPSCode:, - shouldRunPrintPanel: (Object 
Methods) 
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read: 


- read:(NXTypedStream *)stream 

Reads the Window and its Views from the typed stream stream. 

See also: - write: 

reenableDisplay 

- reenableDisplay 

Counters the effect of disableDisplay, reenabling the display methods defined in the 
View class to display Views located within the Window. Returns self. 

See also: - disableDisplay, - isDisplayEnabled, - display::: (View) 

reenableFlushWindow 

- reenableFlushWindow 

Reenables the flush Window method for the Window after it was disabled through a 
previous disableFlushWindow message. Returns self. 

See also: - disableFlushWindow, - flush Window 

removeCursorRect:cursor:forView: 

- removeCursorRect: (const NXRect *)aRect 

cursor :anObj 
forView:aV/ew 

Invoked by View’s removeCursorRect:cursor: method. Do not use this method; use 
removeCursorRect:cursor: instead. 

See also: - removeCursorRect:cursor: (View), - resetCursorRects (View) 

removeFr omE ventMask: 

- (int)removeFromEventMask:(int)tf/d£vefl?s 

Removes the event types specified by oldEvents from the Window’s event mask, and 
returns the old mask. 

This method is typically used when an object sets up its own modal event loop to 
respond to certain events. The return value should be used to restore the Window’s 
original event mask when the modal loop is done. 

See also: - eventMask, - setEventMask:, - addToEventMask: 
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resetCursorRects 

- resetCursorRects 

Removes all existing cursor rectangles from the Window, then recreates the cursor 
rectangles by sending a resetCursorRects message to every View in the Window’s 
view hierarchy. Returns self. 

This method is typically invoked by the Application object when it detects that the key 
window’s cursor rectangles are invalid. In program code, it’s more efficient to send a 
invalidateCursorRectsForView: message to fix incorrect cursor rectangles, rather 
than resetCursorRects. 

See also: - invalidateCursorRectsForView:, - resetCursorRects (View) 

resignKeyWindow 

- resignKeyWindow 

Records the fact that the receiver is no longer the key window, then passes the 
resignKeyWindow message on to the first responder, if the first responder can respond. 
The Window’s delegate is sent a windowDidResignKey: message, if it can respond. 
Returns self. 

The Application object sends a resignKeyWindow message to the current key window 
whenever another Window is about to be made the new key window. 

If you define a Window subclass and implement your own version of this method, it 
should include a message to super to perform this version as well. 

See also: - becomeKeyWindow, - resignMainWindow, - setDelegate: 

resignMainWindow 

- resignMainWindow 

Records the fact that the receiving Window is no longer the main window, and sends 
the Window’s delegate a windowDidResignMain: message to notify it of the change 
in status, if the delegate can respond. Returns self. 

The Application object sends a resignMainWindow message to the current main 
window whenever another Window is about to become the new main window. 

See also: - becomeMainWindow, - resignKeyWindow 
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r ightMouseDown: 

- rightMouseDown:(NXEvent *)theEvent 

Responds to uncaught right mouse-down events by passing the message on the 
Application object. By default, a right mouse-down event in a window causes the main 
menu to pop up under the cursor. Returns the Application object. 

See also: - rightMouseDown: (Application) 

screen 

- (const NXScreen *)screen 

Returns a pointer to the screen that the Window is on. If the Window is partly on one 
screen and partly on another, the screen where most of it lies is the one returned. 

See also: - bestScreen 
screenChanged: 

- screenChanged: (NXEvent *)theEvent 

Responds to a screen-changed subevent (of the kit-defined event) by sending the 
Window’s delegate a windowDidChangeScreen: message, if the delegate can 
respond. If the Window has a dynamic depth limit, this method also changes the depth 
limit to match the new device. 

A screen-changed subevent is generated when the user releases the mouse button after 
dragging a window partially or all the way onto another screen. 

sendEvent: 

- sendEvent: (NXEvent *)theEvent 

Dispatches mouse and keyboard events sent to the Window by the Application object. 
This method is part of the main event loop and should never be invoked in program 
code. 

setBackgroundColor: 

- setBackgroundColor : (NXColor)co/c>r 

Sets the background color of the Window to color. If set, the background color is used 
in place of the background gray when the Window is on a color screen. Returns self. 

See also: - backgroundColor 
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setBackgroundGray: 

- setBackgroundGray: (float )value 

Sets the background gray of the Window, value should lie in the range 0.0 (black) to 
1.0 (white). To obtain pure shades of gray, use one of the following constants: 

NX_BLACK 

NX_DKGRAY 

NX_LTGRAY 

NX_WHITE 

Returns self. 

See also: - backgroundGray 

setContentView: 

- setContentView:aVzew 

Makes aView the Window’s content view after removing the former content view from 
the Window’s view hierarchy. aView is resized so that it exactly fills the content area 
of the Window; its superview, nextResponder, and window instance variables are 
altered to reflect its new status. This method returns the id of the former content view 
so that you can free it or assign it another position in a view hierarchy. Once the content 
view is set, you should not attempt to change its frame rectangle by sending it a 
setFrame:, moveTo::, sizeTo::, or other message. The content view’s frame is reset 
by the Window whenever the window is resized. 

See also: - content View 

setDelegate: 

- setDe\egate:anObject 

Makes anObject the Window’s delegate, and returns self. The delegate is given a 
chance to respond to action messages that work their way up the responder chain to the 
Window (through Application’s sendAction:to:from: method). It can also respond to 
notification messages sent by the Window. See “METHODS IMPLEMENTED BY 
THE DELEGATE” near the end of this class specification. 

See also: - delegate, - trvToPerform:with:, - sendAction:to:from: (Application) 
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setDepthLimit: 

- setDepthLimit : (NX WindowDepth)//m/r 

Sets the depth limit of the Window to limit, which should be one of the following 
enumerated values (defined in the header file appkit/graphics.h): 

NX_TwoB itGray Depth 
NX_EightB itGray Depth 
NX_TwelveB itRGBDepth 
NX_TwentyFourB itRGB Depth 

Returns self. 

See also: - depthLimit, + defaultDepthLimit, - setDynamicDepthLimit: 

setDocEdited: 

- setDocEdited :(QOOL)flag 

Sets whether or not the document displayed in the Window has been edited but not 
saved. If flag is YES, the Window’s close button will display a broken “X” to indicate 
that the document needs to be saved. If flag is NO, the close button will be shown with 
a solid “X”. The default is NO. Returns self. 

See also: - isDocEdited 

setDynamicDepthLimit: 

- setDynamicDepthLimit :(BOOL]/?ag 

Sets whether the Window’s depth limit should change to match the depth of the display 
device that it’s on. If flag is YES, the depth limit will depend on which screen the 
Window is on. If flag is NO, the Window will have the default depth limit. A different, 
and nondynamic, depth limit can be set with the setDepthLimit: method. Returns self. 

See also: - hasDynamicDepthLimit, + defaultDepthLimit, - setDepthLimit: 


setEventMask: 

- (int)setEventMask:(int)«ewM<zs£ 

Assigns a new event mask to the Window and returns the original event mask. The 
mask tells the Window Server which types of events the Window wants to receive. It’s 
formed by joining the masks for individual events using the bitwise OR operator. The 
constants for individual event masks are listed below. Those that are included in the 
default event mask for a Window are marked with an asterisk. 
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* NX_LMOUSEDOWNMASK 

* NX_LMOUSEUPMASK 

* NX_RMOUSEDOWNMASK 

* NX_RMOU SEUPM AS K 
NX_MOUSEMOVEDMASK 
NX_LMOU S EDR AGGEDM AS K 
NX_RMOU SEDRAGGEDMASK 

* NX_MOUSEENTEREDMASK 

* NX_MOU SEEXITEDMASK 

* NX_KEYDOWNMASK 

* NX_KEYUPMASK 
NX_FLAGSCHANGEDMASK 

* NX_KITDEFINEDM AS K 

* NX_APPDEFINEDMASK 

* NX_SYSDEFINEDMASK 
NX_CURSORUPDATEMASK 
NX_JOURNALEVENTMASK 
NX_NULLEVENTMASK 


Miniwindows and application icons have the same default event mask as other 
Windows, except that all keyboard events are excluded. The default mask for a Menu 
includes only left and right mouse-down, mouse-up, and mouse-dragged events and the 
kit-defined event. 


See also: - eventMask, - addToEventMask:, - removeFromEventMask: 


setExcludedFromWindowsMenu: 

- setExcludedFromWindowsMenu: (BOOL)flag 

Sets whether the Window will be excluded from the Windows menu. If flag is YES, it 
won’t be listed in the menu. If flag is NO, it will be listed when it or its miniwindow is 
on-screen. The default is NO. Returns self. 

See also: - isExcludedFromWindowsMenu 

setFreeWhenClosed: 

- setFreeWhenClosed :(BOOL)flag 

Determines the Window’s behavior when it receives a close message. If flag is NO, the 
Window is just hidden (taken out of the screen list). If flag is YES, the Window is 
hidden and then freed. The default for Windows is YES; the default for Panels and 
Menus is NO. Returns self. 

See also: - close, - free 
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setHideOnDeacti vate: 

- setHideOnDeactivate:(BOOL)/fag 

Determines whether the Window will disappear when the application is inactive. If flag 
is YES, the Window is hidden (taken out of the screen list) when the application stops 
being the active application. If flag is NO, the Window stays on-screen. The default 
for Windows is NO; the default for Panels and Menus is YES. Returns self. 

See also: - doesHideOnDeactivate: 

setMiniwindowIcon: 

- setMiniwindowIcon ‘.(const char *)name 

Sets the icon to be used during window miniaturization. There is a 48-by-48 pixel area 
available on a miniaturized window for displaying an icon. The NXImage class will 

look in the_ICON,_EPS, and_TIFF segments of the application executable to 

create the icon upon miniaturization if it’s not already available. 

See also: - miniwindowlcon, - windowWillMiniaturizertoMiniwindow: 

setOneShot: 

- setOneShot :(BOOL)^g 

Sets whether the physical window that the Window object manages should be freed 
when it’s removed from the screen list (and another one created if it’s returned to the 
screen). This is appropriate behavior for windows that the user might use once or twice 
but not display continually. The default is NO. Returns self. 

See also: - isOneShot 

setTitle: 

- setTitle: (const char *)aString 

Changes the string that appears in the Window’s title bar to aString. You don’t have to 
redisplay the Window to make the new title appear. Returns self. 

See also: - title, - setTitleAsFilename: 
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setTitleAsFilename: 

- setTitleAsFilename: (const char *)aString 

Sets aString to be the title of the Window, but formats it as a pathname to a file. The 
file name is displayed first, followed by an em dash and the directory path. The em dash 
is offset by two spaces on either side. For example: 

MyFile — /Net/server/group/home 

The string can be a full or relative pathname. If it lacks any 7’ characters, it won’t be 
formatted. 

Returns self. 

See also: - title, - setTitle: 

setTrackingRect: inside: owner: tag: left: right: 

- setTrackingRect: (const NXRect *)aRect 

inside: (BOOL )insideFlag 
ownerianObject 
tag : (int )trackN um 
left: (BOOL )leftDown 
right: (BOOL )rightDown 

Sets up a tracking rectangle in the Window through the settrackingrect operator. The 
first argument, aRect, is a pointer to the tracking rectangle and is specified in the 
Window’s current coordinate system. The second argument, insideFlag, indicates 
whether the cursor starts off inside the rectangle (YES) or outside it (NO). The third 
argument, anObject, is the id of the object, usually a View or an NXCursor, that will 
handle the mouse-entered and mouse-exited events that are generated for the rectangle; 
the Application object dispatches these events directly to the responsible object. The 
fourth argument, trackNum, is a number that you assign to identify the rectangle. 

If leftDown is YES, the Window Server will generate mouse-entered and mouse-exited 
events for the rectangle only while the left mouse button is down; if rightDown is YES, 
events are generated only while the right button is down. 

Returns self. 

See also: - discardTrackingRect: 
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size Window:: 

- size Window: (NXCoord)w/dr/z :(NXCoord )height 

Resizes the window so that its content area has the specified width and height in base 
coordinates. The lower left comer of the window remains constant. Returns self. 

See also: - placeWindow: 

smartFaxPSCode: 

- smartFaxPSCode:s^«der 

Prints the Window (all the Views in its view hierarchy including the frame view) to a 
fax modem so that it will fit on a single sheet of paper. This method tries to set up the 
various parameters of the printing machinery to create a pleasing result. The image is 
centered horizontally and vertically, and the orientation of the paper (portrait or 
landscape) is set to match the dimensions of the window. These settings are temporary, 
however, and do not permanently affect the global Printlnfo object. 

In the current user interface, faxing is initiated from within the Print panel. However, 
with this method, you can provide users with an independent control for faxing a 
Window. 

This method normally brings up the Fax panel before actually beginning printing. But 
if sender implements a shouIdRunPrintPanel: method, that method will be invoked 
to first query whether to run the panel. If shouIdRunPrintPanel: returns NO, the Fax 
panel won’t be displayed, and the Window will be printed using the last settings of the 
panel. 

A return value of nil indicates that there were errors in generating the PostScript code 
or that the user canceled the job. 

See also: - faxPSCode:, - smartPrintPSCode:, - shouIdRunPrintPanel: (Object 
Methods) 

smartPrintPSCode: 

- smartPrintPSCode:se«der 

Prints the Window (all the Views in its view hierarchy including the frame view) on a 
single sheet of paper. This method tries to set up the various parameters of the printing 
machinery to create a pleasing result. The image is centered horizontally and vertically, 
and the orientation of the paper (portrait or landscape) is set to match the dimensions 
of the window. These settings are temporary, however, and do not permanently affect 
the global Printlnfo object. 
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This method normally brings up the Print panel before actually beginning printing. But 
if sender implements a shouldRunPrintPanel: method, that method will be invoked 
to first query whether to run the panel. If shouldRunPrintPanel: returns NO, the Print 
panel won’t be displayed, and the Window will be printed using the last settings of the 
panel. 

A return value of nil indicates that there were errors in generating the PostScript code 
or that the user canceled the job. 

See also: - printPSCode:, - smartFaxPSCode:, - shouldRunPrintPanel: (Object 
Methods) 

spoolFile: 

- spoolFile: (const char *)-filename 

Spools the generated PostScript code in filename to the printer. This method is invoked 
automatically when printing (or faxing) the Window. 

See also: - openSpoolFile: 
style 

- (int)style 

Returns one of several values, indicating the Window’s style: 

NX_PLAINSTYLE 

NXjriTLEDSTYLE 

NX_RESIZEBARSTYLE 

NX_MENUST YLE 

NX.MINIWINDOWSTYLE 

NX_MINIWORLDSTYLE 

NX_TOKENST YLE 

See also: - initContent:style:backing:buttonMask:defer: 
title 

- (const char *)title 

Returns the string that appears in the title bar of the window. If the title was formatted 
by the setTitleAsFilename: method, the formatted string is returned. 

See also: - setTitle:, - setTitleAsFilename: 
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try ToPerform: with: 

- (BOOL)tryToPerform:(SEL)<2«Acf/ew with lanObject 

Overrides Responder’s version of tryToPerform:with: to give the Window’s delegate 
a chance to respond to the action message. If successful in finding a receiver that 
accepts the anAction message (that doesn’t return nil), this method returns YES. 
Otherwise, it returns NO. 

See also: - tryToPerformrwith: (Responder) 

update 

- update 

Implemented by subclasses to automatically update the Window and redisplay it. 
Returns self. 

A Window receives a update message: 

• After each event, if the Window is in the screen list and the Application object has 
been instructed to automatically update all Windows. The Application object sends 
an update message to every visible Window after each event has been handled in 
the main event loop. 

• Before the Window is placed in the screen list. 

• Before the Window receives a commandKey: message. 

The message gives the Window a chance to make any changes in its state or display that 
are contingent on the way an event was handled. 

Window’s default version of the update method sends the delegate a 
windowDidUpdate: message, if the delegate can respond. Subclass versions of the 
method should send a message to super to incorporate Window’s version after 
completing the update and just before returning. The Menu class implements this 
method to disable and enable menu commands as appropriate. 

See also: - updateWindows (Application), - set Autoupdate: (Application) 

useOptimizedDrawing: 

- useOptimizedDrawing:(BOOL)/ag 

Informs the Window whether to optimize focusing and drawing when Views are 
displayed. The optimizations may prevent sibling subviews from being displayed in 
the correct order. This matters only if the subviews overlap. Always set flag to YES if 
there are no overlapping subviews within the Window. The default is NO. Returns self. 
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validRequestorForSendType:andReturnType: 

- validRequestorFor S endTy pe: (NX Atom)typeSe nt 

andReturnTy pe : (NX Atom )typeReturned 

Passes this message on to the Window’s delegate, if the delegate can respond (and isn’t 
a Responder with its own next responder). If the delegate can’t respond or returns nil, 
this method passes the message to the Application object. If the Application object 
returns nil, this method also returns nil, indicating that no object was found that could 
supply typeSent data for a remote message from the Services menu and accept back 
typeReturned data. If such an object was found, it is returned. 

Messages to perform this method are initiated by the Services menu. It’s part of the 
mechanism that passes validRequestorFor SendType: andReturnTy pe: messages up 
the responder chain. 

See also: - validRequestorForSendType:andReturnType: (Responder and 
Application) 

width Adj ustLimit 

- (float) width Adj ustLimit 

Returns the fraction of a page that can be pushed onto the next page to prevent items 
from being cut in half. The limit applies to horizontal pagination. By default, it’s 0.2. 

This method is invoked during automatic pagination when printing (or faxing) the 
Window; it should not be used in program code. However, you can override it to return 
a different value. The value returned should lie between 0.0 and 1.0 inclusive. 

See also: - heightAdjustLimit 
windowExposed: 

- windowExposed: (NXEvent *)theEvent 

Responds to a window-exposed event by displaying the portion of the window that the 
event record indicates should be redrawn, and informing the delegate through a 
windowDidExpose: message. Returns self. 

See also: - display:: (View), - setDelegate: 
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windowMoved: 


- windowMoved :(NXEvent *)theEvent 

Responds to a window-moved event by recording the new location of the window, and 
informing the Window delegate through a windowDidMove: message. Returns self. 

If you define a Window subclass and implement your own version of this method, it 
should include a message to super to apply this version as well. 

See also: - dragFrom::eventNum:, - setDelegate: 

windowNum 

- (int)windowNum 

Returns the window number of the window corresponding to the receiving Window 
object. If the Window object doesn’t currently have a window, the return value will be 
equal to or less than 0. 

See also: - initContent:style:backing:buttonMask:defer:, - setOneShot: 
windowResized: 

- windowResized :(NXEvent *)theEvent 

Responds to a window-resized event by recording the new dimensions of the window 
and causing it to redisplay. Returns self. 

Window-resized events are not real events; they’re not placed in the event queue. The 
frame view sends the Window object a windowResized: message after the user has 
resized the window from the resize bar. While the window is being resized, the 
Window’s delegate receives repeated windowWillResizeitoSize: messages giving it 
the opportunity to constrain the future size of the window. After the resizing is 
completed, this windowResized: method sends the delegate a windowDidResize: 
message. 

See also: - display:: (View) 

worksWhenModal 

- (BOOL)worksWhenModal 

Returns whether the Window is able to receive keyboard and mouse events even when 
there’s a modal panel (an attention panel) on-screen. The default is NO. Only Panels 
should change this default. 

See also: - set WorksWhenModal: (Panel) 
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write: 


- write :(NXTypedStream *)stream 

Writes the receiving Window to the typed stream stream , along with its content view 
and miniwindow counterpart. The delegate and field editor are not explicitly written, 
but all subviews of the content view will be. 

See also: - read: 


METHODS IMPLEMENTED BY THE DELEGATE 

windowDidBecomeKey: 

- windowDidBecomeKey '.sender 

Responds to a message informing the delegate that the sender Window has just become 
the key window. 

See also: - becomeKey Window 

windowDidBecomeMain: 

- windowDidBecomeMain ‘.sender 

Responds to a message informing the delegate that the sender Window has just become 
the main window. 

See also: - becomeMainWindow 

windowDidChangeScreen: 

- windowDidChangeScreen '.sender 

Responds to a message informing the delegate that the sender Window has received a 
screen-changed subevent (of the kit-defined event). 

See also: - screenChanged: 

windowDidDeminiatur ize: 

- windowDidDeminiaturize:seftder 

Responds to a message informing the delegate that the user has double-clicked the 
sender Window’s miniwindow counterpart, returning the Window to the screen and 
hiding the miniwindow. 

See also: - deminiaturize:, - windowDidMiniaturize: 
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windowDidExpose: 

- windowDidExpose ’.sender 

Responds to a message informing the delegate that the sender Window received a 
window-exposed subevent of the kit-defined event. 

See also: - windowExposed: 

windowDidMiniatur ize: 

- windowDidMiniaturize: sender 

Responds to a message informing the delegate that the user has miniaturized the sender 
Window. 

See also: - windowWillMiniaturizeitoMiniwindow:, - windowDidDeminiaturize: 

windowDidMove: 

- windo wD id Move: sender 

Responds to a message informing the delegate that the user moved the sender Window. 
See also: - windowMoved: 

windowDidResignKey: 

- windowDidResignKey:sender 

Responds to a message informing the delegate that the sender Window is no longer the 
key window. 

See also: - resignKeyWindow 

windowDidResignMain: 

- windowDidResignMain: sender 

Responds to a message informing the delegate that the sender Window is no longer the 
main window. 

See also: - resignMainWindow 
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windowDidResize: 

- windowDidResizei^wder 

Responds to a message informing the delegate that the user has finished resizing the 
sender Window. The new size of the Window can be obtained by sending it a 
getFrame: message. 

See also: - windowWillResize:toSize:, - getFrame: 

windowDidUpdate: 

- windowDidUpdate:se«der 

Responds to a message that’s sent when the sender Window receives an update 
message. 

See also: - update 

windowWillClose: 

- windowWillClose '.sender 

Responds to a message informing the delegate that the sender Window is about to close. 
If the delegate returns nil, the Window won’t close. 

windowWilIMiniaturize:toMiniwindow: 

- windowWillMiniaturize:.s<?tt<ic/ toMiniwindow \miniwindow 

Responds to a message informing the delegate that the user will miniaturize the sender 
Window. The delegate can install a special content View for miniwindow, or set its title. 
The default title is the same as sender's. 

See also: - windowDidMiniaturize:, - miniaturize: 

windowWillResize:toSize: 

- windowWillResize:s<?/2<i<?r toSize:(NXSize *)frameSize 

Responds to a message informing the delegate that the user is trying to resize the sender 
Window. During window resizing, the delegate is sent continuous 
windowWillResize:toSize: messages as the user drags the window’s outline. The 
second argument, frameSize, is a a pointer to an NXSize structure containing the size 
(in screen coordinates) that the window will be resized to. If the delegate wants to 
constrain the window size, it may update the structure to the desired size. The window 
outline is displayed at the constrained size provided by the delegate. 

See also: - windowDidResize:, - windowResized: 
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windowWillReturnFieldEditor:toObject: 

- windowWillReturnFieldEditorisc/ider toObjediclient 

Responds to a message informing the delegate that client has requested the sender 
Window’s field editor, the Text object that performs various editing tasks within the 
Window. If the delegate’s implementation of this method returns an object other than 
nil, the Window substitutes it for the field editor and returns it to client. 

See also: - getFieldEditor:for: 


CONSTANTS AND DEFINED TYPES 

/* 

* Window styles 
*/ 

#define NX_PLAINSTYLE 0 

#define NX_TITLEDSTYLE 1 

#define NX_MENUSTYLE 2 

#define NX_MINIWINDOWSTYLE 3 

#define NX_MINIWORLDSTYLE 4 

fdefine NX_TOKENSTYLE 5 

#define NX_RESIZEBARSTYLE 6 

#define NX_FIRSTWINSTYLE NX_PLAINSTYLE 

#define NX_LASTWINSTYLE NX_RESIZEBARSTYLE 

#define NX_NUMWINSTYLES \ 

(NX_LASTWINSTYLE - NX_FIRSTWINSTYLE + 1) 

/* 

* Control masks 
*/ 

#define NX_CLOSEBUTTONMASK 1 

#define NX_RESIZEBUTTONMASK 2 

#define NX_MINIATURIZEBUTTONMASK 4 

tdefine NX_ALLBUTTONS \ 

(NX_CLOSEBUTTONMASK|NX_RESIZEBUTTONMASK|NX_MINIATURIZEBUTTONMASK) 

/* 

* Sizes of icon images and windows 


*/ 

#define NX__ICONWIDTH 48.0 
#define NX__ICONHEIGHT 48.0 
#define NX_TOKENWIDTH 64.0 
#define NX TOKENHEIGHT 64.0 
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/* 

* Window tiers 
*/ 

#define NX_NORMALLEVEL 0 

#define NX_FLOATINGLEVEL 3 

#define NX_DOCKLEVEL 5 

#define NX_SUBMENULEVEL 10 

#define NX MAINMENULEVEL 20 
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Chapter 3 
C Functions 


This chapter gives detailed descriptions of the C functions provided by NeXT. Also 
included here are some macros that behave like functions. For this chapter, the functions 
and macros are divided into two groups: 

• NeXTStep, which includes functions and macros defined in the Application Kit, 
functions for using streams and typed streams, and Display PostScript functions 

• Run-time functions for the Objective-C language 

Within these divisions, functions are subgrouped with other functions that perform related 
tasks. These subgroups are described in alphabetical order by the name of the first function 
listed in the subgroup. Functions within subgroups are also listed alphabetically, with a 
pointer to the subgroup’s description. 

For convenience, these functions are summarized in the NeXT Technical Summaries 
manual. The summary lists functions by the same subgroups used in this chapter and 
combines several related subgroups under a heading such as “Rectangle Functions” or 
“Stream Functions.” The calling sequence for each function is shown in the summary. 

Note that under the SYNOPSIS heading in the function descriptions, the lowest-level 
header file is specified in the #import statement; you might instead include a header file 
like appkit/appkit.h, which includes many other, lower-level header files. For details on 
these files, see Chapter 1, “Data Types and Constants.” 


NeXTStep Functions 

This section contains descriptions of two types of functions: those that implement NeXT’s 
system-dependent interface to the Display PostScript system and those that support the 
various Application Kit classes. The Display PostScript system functions have a “DPS” 
prefix; the Application Kit functions have an “NX” prefix. The descriptions of the “DPS” 
functions assume knowledge of the Display PostScript system. For the primary 
documentation of this system, refer to Extensions for the Display PostScript System and 
Client Library Reference Manual, both by Adobe Systems Incorporated. See “Suggested 
Reading” in Technical Summaries for information on Adobe documentation. 
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DPSAddFDQ, DPSRemoveFD() 


SUMMARY Add or remove monitored file descriptor 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSAddFD(int/d, DPSFDProc handler, void *userData, int priority ) 
void DPSRemoveFD(int fd) 

DESCRIPTION 

DPSAddFD() adds a file descriptor to the list of those that the client library can check 
each time it attempts to retrieve an event. The integer fd is the file descriptor (as 
returned by open()) to be added. When data can be read from the file identified by fd, 
the function handler is called (assuming an appropriate value of priority, as explained 
below). The third argument, userData, is a pointer that the application can use to pass 
some data to handler. 

The integer priority lets you specify the execution priority of handler. A priority level 
can be from 0 to 30. During normal execution of a program based on the Application 
Kit, the function that returns events from the Window Server will check fd if priority is 
NX_BASETHRESHOLD (a value of 1) or higher. When the application displays an 
attention panel, fd is checked only if priority is NX_RUNMODALTHRESHOLD (a 
value of 5) or higher. During a modal event loop ,fd is checked only if priority is 
NX_MODALRESPTHRESHOLD (a value of 10) or higher. 

Note: NX_BASETHRESHOLD, NX_RUNMODALTHRESHOLD, and 
NX_MODALRESPTHRESHOLD are defined in the header file 

appkit/Application.h. 

The function registered as handler has the form: 
voidfunc(intfd, void * userData) 

where fd is the file descriptor of the file that’s ready to be read and userData is a 
reference to the data you specified in the call to DPSAddFD(). 

DPSRemoveFDO removes the specified file descriptor from the list of those that the 
application will check. 

SEE ALSO 

DPSAddPortQ, DPSAddTimedEntryO 
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DPSAddPortQ, DPSRemovePort() 


SUMMARY Add or remove monitored Mach port 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSAddPort(port_t newPort, DPSPortProc handler, int maxSize, 
void *userData, int priority) 
void DPSRemovePort(port_t port) 

DESCRIPTION 

DPSAddPort() adds a Mach port to the list of ports that an application based on the 
Application Kit can check each time it attempts to retrieve an event. newPort identifies 
the Mach port to be monitored. When a message arrives at the port, the function 
handler is called (assuming an appropriate value of priority, as explained below). The 
type DPSPortProc is defined in the header file dpsclient/dpsNeXT.h. The maxSize 
argument declares the maximum size of the in-line data (including the message header) 
that will be received in the message. The pointer userData can be used to pass some 
data to handler. 

The integer priority lets you specify the execution priority of handler. A priority level 
can be from 0 to 30. During normal execution of a program based on the Application 
Kit, the function that returns events from the Window Server will check newPort if 
priority is NX_BASETHRESHOLD (a value of 1) or higher. When the application 
displays a modal panel, newPort is checked only if priority is 
NX_RUNMODALTHRESHOLD (a value of 5) or higher. During a modal event loop, 
newPort is checked only if priority is NX_MODALRESPTHRESHOLD (a value of 10) 
or higher. 

Note: NX_BASETHRESHOLD, NX_RUNMODALTHRESHOLD, and 
NX_MODALRESPTHRESHOLD are defined in the header file 

appkit/Application.h. 

The function registered as handler has the form: 

void/M«c(msg_header_t *msg, void *userData) 

where msg is a pointer to the message that was received at the port and userData is a 
reference to the data you specified in the call to DPSAddPort(). 

If, within handler, you want to call msg_receive() to receive further messages at the 
port, you must first call DPSRemovePortO to remove the port from the system’s port 
set. (This is because your application can’t receive messages from a port that’s in a port 
set.) After your application is finished receiving messages directly from the port, it can 
call DPSAddPortQ to have the system continue to monitor the port. 
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The message buffer identified by msg is overwritten whenever your application gets 
events, receives values from the Window Server, or receives data from a monitored 
port. If you want to preserve the message, copy the contents of the message buffer into 
local storage before you take an action that might overwrite it. 

DPSRemovePort() removes the specified port from the list of those that the application 
will check. 

The Application Kit provides an object-oriented interface to Mach ports through the 
Listener and Speaker classes. To send messages between two applications based on the 
Application Kit, use Speaker and Listener objects. To monitor a Mach port directly, 

use DPSAddPortQ. 


DPSAddTimedEntryO, DPSRemoveTimedEntryO 

SUMMARY Add or remove timed entry 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

DPSTimedEntry DPSAddTimedEntry(double period, DPSTimedEntryProc handler, 
void *userData, int priority) 

void DPSRemoveTimedEntry(DPSTimedEntry teNumber) 

DESCRIPTION 

DPSAddTimedEntryO registers handler as a “timed entry,” a function that’s called 
repeatedly at a given time interval, period determines the number of seconds between 
calls to the timed entry. Whenever an application based on the Application Kit attempts 
to retrieve events from the event queue, it also checks (depending on priority ) to 
determine whether any timed entries are due to be called. userData is a pointer that 
you can use to pass some data to the timed entry. 

The integer priority lets you specify the execution priority of handler. A priority level 
can be from 0 to 30. During normal execution of a program based on the Application 
Kit, the function that returns events from the Window Server will check if handler is 
due to be called if priority is NX_BASETHRESHOLD (a value of 1) or higher. When 
the application displays a modal panel, handler is checked only if priority is 
NX_RUNMODALTHRESHOLD (a value of 5) or higher. During a modal event loop, 
handler is checked only if priority is NX_MODALRESPTHRESHOLD (a value of 10) 
or higher. 

Note: NX_BASETHRESHOLD, NX_RUNMODALTHRESHOLD, and 
NX_MODALRESPTHRESHOLD are defined in the header file 

appkit/ Application, h. 
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The function registered as handler has the form: 


void func (DPSTimedEntry teNumber, double now, char *userData) 

where teNumber is the timed entry identifier returned by DPSAddTimedEntryO, now 
is the number of seconds since some arbitrary point in the past, and userData is the 
pointer DPSAddTimedEntryO received when this timed entry was installed. 

DPSRemoveTimedEntryO removes a previously registered timed entry. 

RETURN 

DPSAddTimedEntryO returns a number identifying the timed entry or -1 to indicate 
an error. 


DPSCreateContextO, DPSCreateContextWithTimeoutFromZone(), 
DPSCreateStreamContextO 

SUMMARY Create PostScript execution context 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

DPSContext DPSCreateContext(const char *hostName, const char *serverName, 
DPSTextProc textProc, DPSErrorProc errorProc ) 

DPSContext DPSCreateContextWithTimeoutFromZone(const char *hostName, 
const char *serverName, DPSTextProc textProc, DPSErrorProc errorProc, 
int timeout, NXZone *zone) 

DPSContext DPSCreateStreamContext(NXStream * stream, int debugging, 
DPSProgramEncoding progEnc, DPSNameEncoding nameEnc, 

DPSErrorProc errorProc) 

DESCRIPTION 

DPSCreateContextO establishes a connection with the Window Server and creates a 
PostScript execution context in it. The new context becomes the current context. The 
first argument, hostName, identifies the machine that’s running the Window Server; the 
second argument, serverName, identifies the Window Server that’s running on that 
machine. With these two arguments and the help of the Mach network server 
nmserver, the Mach port for the Window Server can be identified. If hostName is 
NULL, the network server on the local machine is queried for the Window Server’s 
port. If serverName is NULL, a well-known name for the Window Server is used. If 
both arguments are NULL, DPSCreateContextO checks to see whether access rights 
to the Window Server’s port have been inherited from the application’s parent. (For 

TM 

example, an application launched by the Workspace Manager gains a connection to 
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the Window Server by inheriting it from the Workspace Manager.) If the rights weren’t 
inherited from the parent, DPSCreateContext() queries the local machine for the 
Window Server’s port using a well-known name. 

The last two arguments, textProc and errorProc , refer to call-back procedures that 
handle text returned from the Window Server and errors generated on either side of the 
connection. See “Handling Output” in the Client Library Reference Manual by Adobe 
Systems Incorporated for more details. 

For an application that’s based on the Application Kit, you could create an additional 
context by making this call: 


DPSContext context; 

context = DPSCreateContext(NXGetDefaultValue([NXApp appName], 
"NXHost"),NXGetDefaultValue([NXApp appName], 
"NXPSNanae") , 

NULL, NULL); 

This example queries the application’s default values for the indentity of the host 
machine and the Window Server. By doing this, the new context is created in the 
correct Window Server even if that Server is not on the same machine as the application 
process. 

The context that DPSCreateContext() creates allocates memory from the default 
allocation zone. Also, when there’s difficulty creating the context, 
DPSCreateContextO waits up to 60 seconds before raising an exception. If you want 
to change either of these parameters, use 

DPSCreateContextWithTimeoutFromZone(). Its two additional arguments let you 
specify the zone for the context to use when allocating context-specific data and a 
timeout value in milliseconds. 

DPSCreateStreamContextO is similar to DPSCreateContextO, except that the new 
context is actually a connection from the client application to a stream. This connection 
becomes the current context. PostScript code that the application generates is sent to 
the stream (which may have memory, a file, or a Mach port as a destination) rather than 
to the Window Server. The first argument, stream , is a pointer to an NXStream, as 
created by NXOpenFileO or NXMapFiIe(). The debugging argument is intended for 
debugging purposes but is not currently implemented. progEnc and nameEnc specify 
the type of program and user-name encodings to be used for output to the stream. (See 
Extensions for the Display PostScript System for more information.) The last 
argument, errorProc , identifies the procedure that’s called when errors are generated. 

Few programmers will need to call either of these functions directly: The Application 
Kit manages contexts for programs based on the Kit. For example, when an application 
is launched, its Application object calls DPSCreateContextO to create a context in the 
Window Server. Similarly, to print a View the Kit calls DPSCreateStreamContextO 
to temporarily redirect PostScript code from the View to a stream. 
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RETURN 


Each of these functions returns the newly created DPSContext, as defined in the header 
file dpsclient/dpsfriends.h. 

EXCEPTIONS 

DPSCreateContextO and DPSCreateContextWithTimeoutFromZone() raise a 
dps_err_outOfMemory exception if they encounter difficulty allocating ports or other 
resources for the new context. They raise a dps_err_cantConnect exception if they 
can’t return a context within the timeout period. 


DPSCreateContextWithTimeoutFromZone() —> See DPSCreateContextO 
DPSCreateStreamContextO —> See DPSCreateContextO 


DPSDefmeUserObjectO, DPSUndefineUserObjectO 

SUMMARY Return index for top object of operand stack 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

int DPSDefineUserObject(int index) 
void DPSUndefineUserObject(int index ) 

DESCRIPTION 

DPSDefmeUserObjectO associates index with the PostScript object that’s on the top 
of the operand stack, thereby creating a user object. (See Extensions for the Display 
PostScript System for a description of user objects.) If index is 0, the object is assigned 
the next available index number. The function returns the new index, which can then 
be passed to a pswrap-generated function that takes a user object. 

To avoid coming into conflict with user objects defined by the client library or 
Application Kit, use DPSDefmeUserObjectO rather than the PostScript operator 
defineuserobject or the single-operator functions DPSdefineuserobject() and 
PSdefineuserobject(). 

DPSUndefineUserObjectO removes the association between index and the PostScript 
object it refers to, thus destroying the user object. By destroying a user object that’s no 
longer needed, you can let the garbage collector reclaim the previously associated 
PostScript object. 
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RETURN 

DPSDefineUserObject(), if successful in assigning an index, returns the index that the 
object was assigned. If unsuccessful, it returns 0. 


DPSDiscardEvents() -> See DPSGetEventO 


DPSDoUserPathO, DPSDoUserPathWithMatrix() 

SUMMARY Send PostScript path to Window Server and execute 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSDoUserPath(void *coords, int numCoords, DPSNumberFormat numType, 
char *ops, int numOps, void *bbox , int action) 
void DPSDoUserPathWithMatrix(void * coords, int numCoords, 

DPSNumberFormat numType , char *ops, int numOps, void *bbox, int action, 
float matrix[6J) 

DESCRIPTION 

DPSDoUserPathO and DPSDoUserPathWithMatrix() send an encoded user path to 
the Window Server and then execute the operator specified by action. (See “User 
Paths” in Extensions for the Display PostScript System for the primary documentation 
on user paths.) The two functions are identical except for the matrix argument required 

by DPSDoUserPathWithMatrix(). 

The encoded user path is described by the coords, ops, and bbox arguments. The bbox 
and coords arguments specify the encoded user path’s data string; the ops argument 
refers to the encoded user path’s operator string. The bbox argument identifies the 
operands for the setbbox operator, and the coords argument identifies the coordinates 
used by the operators encoded in the operator string. You pass the number of elements 
in the coords and ops arguments using the numCoords and numOps arguments. 

The numType argument specifies the type of the numbers used in the data string. The 
header file dpsclient/dpsNeXT.h defines these constants for numType : 

dps_float 

dps_long 

dps_short 
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You can also specify 16 and 32-bit fixed-point numbers. For 16-bit fixed-point 
numbers, use dps_short plus the number of bits in the fractional portion. For 32-bit 
fixed-point numbers, use dps_long plus the number of bits in the fractional portion. 
See “Alternate Language Encodings” in Extensions for the Display PostScript System 
for more information. 


The ops argument refers to an array encoding the operators that will consume the 
operands in the data string. These constants are provided for ops: 


dps_setbbox 

dps_moveto 

dps_rmoveto 

dps_lineto 

dps_rlineto 

dps_curveto 

dps_rcurveto 

dps_arc 

dps_arcn 

dps_arct 

dps_closepath 

dps_ucache 


The first operands in a user path (as identified by bbox ) are consumed by the setbbox 
operator; however, including dps_setbbox in the operator string is optional. If you 
don’t include it, it will be included for you. 

Once the user path has been constructed, the operator specified by action is executed. 
These constants are provided for action: 


dps_uappend 

dps_ufill 

dpsjueofill 

dps_ustroke 

dps_ustrokepath 

dps_inufill 

dps_inueofill 

dps_inustroke 

dps_def 

dps_put 


DPSDoUserPathWithMatrix() ’s matrix argument represents the optional matrix 
operand used by the ustroke, inustroke, and ustrokepath operators. If matrix is 
NULL, the argument is ignored. 
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The following program fragment demonstrates the use of DPSDoUserPath() by 
creating a user path (an isosceles triangle) within a bounding rectangle whose lower left 
comer is located at (0,0) and whose width and height are 200. It then strokes the path. 

short coords[6] = {0, 0, 200, 0, 100, 200}; 
char ops[4] = {dps_moveto, dps_lineto,dps_lineto, 
dps_closepath}; 
short bbox[4] = {0, 0, 200, 200}; 

DPSDoUserPath(coords, 6, dps_short, ops, 4, bbox, dps_ustroke); 


DPSDoUserPathWithMatrix() —> See DPSDoUserPathQ 


DPSFlush() 

SUMMARY Send PostScript code to Window Server 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsdient/dpsclient.h> 
void DPSFlush() 

DESCRIPTION 

DPSFlush() flushes the application’s output buffer, forcing any buffered PostScript 
code or data to the Window Server. DPSFlush() is a cover for 
DPSFlushContext(DPSGetCurrentContextO); for more information about these 
functions, see their descriptions in the Client Library Reference Manual. 
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DPSGetEvent(), DPSPeekEventO, DPSDiscardEvents() 


SUMMARY Access data from Window Server 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

int DPSGetEvent(DPS Context context, NXEvent *anEvent, int mask, double timeout, 
int threshold) 

int DPSPeekEvent(DPSContext context, NXEvent *anEvent, int mask, 
double timeout, int threshold) 
void DPSDiscardEvents(DPSContext context, int mask) 

DESCRIPTION 

DPSGetEvent() and DPSPeekEventO are macros that access event records in an 
application’s event queue. These routines are provided primarily for programs that 
don’t use the Application Kit. An application based on the Kit should use the 
corresponding Application class methods (such as getNextEvent: and 
peekNextEvent:into:) or the function NXGetOrPeekEvent() so that it can be 
journaled. DPSDiscardEvents() removes all event records of a specified type from the 
queue. 

DPSGetEvent() and DPSPeekEventO differ only in how they treat the accessed event 
record. DPSGetEvent() removes the record from the queue after making its data 
available to the application; DPSPeekEventO leaves the record in the queue. 

DPSGetEvent() and DPSPeekEventO take the same parameters. The first, context, 
represents a PostScript execution context within the Window Server. Virtually all 
applications have only one execution context, which can be returned using 
DPSGetCurrentContextO. (See the Client Library Reference Manual for information 
on DPSGetCurrentContextO.) Applications having more than one execution context 
can use the constant DPS_ALLCONTEXTS to access events from all contexts 
belonging to them. 

The second argument, anEvent, is a pointer to an event record. If DPSGetEvent() or 
DPSPeekEventO is successful in accessing an event record, the record’s data is copied 
into the storage referred to by anEvent. 

mask determines the types of events sought. The header file dpsclient/event.h defines 
these constants for mask: 
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Constant 

NXKEYDOWNMASK 

NX_KEYUPMASK 

NX_FLAGSCHANGEDMASK 

NX_LMOUSEDOWNMASK 

NX_LMOUSEUPMASK 

NX_RMOUSEDOWNMASK 

NX_RMOUSEUPMASK 

NX_MOUSEMOVEDMASK 

NX_LMOUSEDRAGGEDMASK 

NX_RMOUSEDRAGGEDMASK 

NX_MOUSEENTEREDMASK 

NX_MOUSEEXITEDMASK 

NX_TIMERMASK 

NX_CURSORUPDATEMASK 

NXJKITDEFINEDMASK 

NX_S Y S DEFINEDM AS K 

NX_APPDEFINEDMASK 

NX_ALLEVENTS 


Event Type 

Key-down 

Key-up 

Flags-changed 

Mouse-down, left or only mouse button 
Mouse-up, left or only mouse button 
Mouse-down, right mouse button 
Mouse-up, right mouse button 
Mouse-moved 

Mouse-dragged, left or only mouse button 

Mouse-dragged, right mouse button 

Mouse-entered 

Mouse-exited 

Timer 

Cursor-update 
Kit-defined 
System-defined 
Application-defined 
All event types 


To check for multiple types of events, you can combine these constants using the 
bitwise OR operator. 


If an event matching the event mask isn’t available in the queue, DPSGetEventO or 
DPSPeekEvent() waits until one arrives or until timeout seconds have elapsed, 
whichever occurs first. The value of timeout can be in the range of 0.0 to 
NX_FOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in 
the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits 
until an appropriate event arrives before returning. 


The last argument, threshold, is an integer in the range 0 through 31 that determines 
which other services may be provided during a call to DPSGetEventO or 
DPSPeekEvent(). 


Requests for services are registered by the functions DPSAddTimedEntryO, 
DPSAddPortO, and DPSAddFD(). Each of these functions takes an argument 
specifying a priority level. If this level is equal to or greater than threshold, the service 
is provided before DPSGetEventO or DPSPeekEventO returns. 

DPSDiscardEvents()’s two parameters, context and mask, are the same as those for 
DPSGetEventO and DPSPeekEventO- DPSDiscardEvents() removes from the 
application’s event queue those records whose event types match mask and whose 
context matches context. 


RETURN 

DPSGetEventO and DPSPeekEventO return 1 if they are successful in accessing an 
event record and 0 if they aren’t. 
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SEE ALSO 

DPSAddFDO, DPSAddPort(), DPSAddTimedEntryO, DPSPostEvent(), 
NXGetOrPeekEvent() 


DPSN ameF romTy pe AndlndexQ 

SUMMARY Provide support for user names 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

const char *DPSNameFromTypeAndIndex(short type, int index ) 

DESCRIPTION 

DPSNameFromTypeAndlndexQ returns the text associated with index from the 
system or user name table. If type is -1, the text is returned from the system name table; 
if type is 0, it’s returned from the user name table. 

The name tables are used primarily by the Client Library and pswrap; few 
programmers will access them directly. (See “System and user name encodings” in the 
“Alternate Language Encodings” section of Extensions for the Display PostScript 
System for more information.) 

RETURN 

This function returns a read-only character string. 


DPSPeekEvent() —> See DPSGetEventQ 


DPSPostEventO 

SUMMARY Post event without involving Window Server 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

int DPSPostEvent(NXEvent *anEvent, int atStart) 
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DESCRIPTION 


DPSPostEventO lets you add an event record to your application’s event queue without 
involving the Window Server. anEvent is a pointer to the event record to be added. 
atStart specifies where the new record will be placed in relation to any other records in 
the queue. If atStart is TRUE, the record is posted in front of all other records and so 
will be the next one your application receives. If atStart is FALSE, the record is posted 
behind all other records and so won’t be returned until records that precede it are 
processed. 

Note that event records you post using DPSPostEventO aren’t filtered by an event filter 
function set with DPSSetEventFunc(). 

RETURN 

DPSPostEventO returns 0 if successful in posting the event record; it returns -1 if 
unsuccessful in posting the record because the event queue is full. 

SEE ALSO 

DPSSetEventFuncO 


DPSPrintErrorO, DPSPrintErrorToStream() 

SUMMARY Handle errors 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSPrintError(FILE *fp, const DPSBinObjSeq error ) 

void DPSPrintErrorToStream(NXStream * stream, const DPSBinObjSeq error) 

DESCRIPTION 

DPSPrintErrorO and DPSPrintErrorToStreamO format and print error messages 
received from a PostScript execution context in the Window Server. The error message 
is extracted from the binary object sequence error. (The type DPSBinObjSeq is defined 
in the header file dpsclient/dpsfriends.h.) DPSPrintErrorO prints the error message 
to the file identified by fp’, DPSPrintErrorToStreamO prints the error message to 
stream. (The NXStream structure is defined in the header file streams/streams.h.) 

You rarely will need to call these functions directly. However, if you reset the error 
handler for a PostScript execution context, the new handler you install could use one of 
these functions to process errors that it receives. See the Client Library Reference 
Manual for more information on error handling. 
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DPSPrintErrorToStreamO —> See DPSPrintError() 
DPSRemoveFD() -> See DPSAddFD() 

DPSRemovePortO —> See DPSAddPort() 
DPSRemoveTimedEntryO —> See DPSAddTimedEntryO 


DPSSetDeadKeysEnabled() 

SUMMARY Enable or disable dead key processing for a context’s events 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSSetDeadKeysEnabled(DPSContext context, int flag) 

DESCRIPTION 

DPSSetDeadKeysEnabled() turns dead key processing on or off for context. If flag is 
0, dead key processing is turned off; otherwise, it’s turned on (the default). 

Dead key processing is a technique for extending the range of characters that can be 
entered from the keyboard. In NeXTStep, it provides one way for users to enter 
accented characters. For example, a user can type Altemate-e followed by the letter “e” 
to produce the letter “e”. The first keyboard input, Altemate-e, seems to have no 
effect—it’s the “dead key”. However, it signals client library routines that it and the 
following character should be analyzed as a pair. If, within NeXTStep, the pair of 
characters has been associated with a third character, a keyboard event record 
representing the third character is placed in the application’s event queue, and the first 
two event records are discarded. If there is no such association between the two 
characters, the two event records are added to the event queue. 

See the NeXT User’s Reference manual for a listing of the keys that produce accent 
characters. 


DPSPrintErrorToStream( ) 
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DPS SetEventFunc() 


SUMMARY Set function that filters events 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

DPSEventFilterFunc DPSSetEventFunc(DPSContext context , 

DPSEventFilterFunc fund) 

DESCRIPTION 

DPSSetEventFunc() establishes the function func as the function to be called when an 
event record is returned from the PostScript context context in the Window Server. The 
registered function is called before the event record is put in the event queue. If the 
registered function returns 0, the record is discarded. If the registered function returns 
1, the record is passed on for further processing. 

Only event records coming from the Window Server are filtered by the registered 
function. Records that you post to the event queue using DPSPostEventO aren’t 
affected. 

The following declaration is provided in the header file dpsclient/dpsNeXT.h for 
convenience: 

typedef int (*DPSEventFilterFunc) (NXEvent *anEvent) ; 


RETURN 

DPSSetEventFunc() returns a pointer to the previously registered event function. This 
lets you chain together the current and previous event functions. 


SEE ALSO 

DPSPostEventO 
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DPSSetTrackingO 


SUMMARY Turn event coalescing on or off 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 
int DPSSetTracking(int flag) 

DESCRIPTION 

DPSSetTrackingO turns event coalescing on or off for the current context. If flag is 0, 
event coalescing is turned off; otherwise, it’s turned on (the default). 

Event coalescing is an optimization that’s useful when tracking the mouse. When the 
mouse is moved, numerous events flow into the event queue. To reduce the number of 
events awaiting removal by the application, adjacent mouse-moved events are replaced 
by the most recent event of the contiguous group. The same is done for left and right 
mouse-dragged events, with the addition that a mouse-up event replaces mouse- 
dragged events that come before it in the queue. 

RETURN 

DPSSetTrackingO returns the previous state of the event-coalescing switch. 


DPSStartWaitCursorTimer() 

SUMMARY Initiate count down for wait cursor 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 
void DPSStartWaitCursorTimer() 

DESCRIPTION 

DPSStartWaitCursorTimer() triggers the mechanism that displays a wait cursor 
when an application is busy and can’t respond to user input. In most cases, wait cursor 
support is automatic: You’ll only need to call this function if your application starts a 
time-consuming operation that’s not initiated by a user-generated event. 

Client library routines and the Window Server cooperate to display the wait cursor 
whenever more than a preset amount of time elapses between the time an application 
takes an event record from the event queue and the time the application is again ready 


DPSSetTrackingO 3-19 



to consume events. However, when an application starts an operation that isn’t initiated 
by an event—such as one caused by receiving a Mach message or by processing data 
from a file (see DPSAddPort() and DPSAddFD()) —the wait cursor mechanism is 
bypassed. To ensure proper wait cursor behavior in these cases, call 
DPSStartWaitCursorTimer() before beginning the time-consuming operation. 

SEE ALSO 

DPSAddFDQ, DPSAddPort(), setwaitcursorenabled 


DPSTraceContext() 

SUMMARY Control debugging tracing of context’s input and output 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

int DPSTraceContext(DPSContext context, int flag) 

DESCRIPTION 

DPSTraceContextO controls the tracing of data between a PostScript execution 
context (or contexts) in the Window Server and an application process. When tracing 
is enabled, a copy of the PostScript code generated by an application and the values 
returned to it by the Window Server is sent to the UNIX® standard error file, stderr. 
This copy can be useful for program debugging and optimization. 

The first argument, context, specifies the context to be traced. An application’s single 
context can be returned with DPSGetCurrentContext(). (See the Client Library 
Reference Manual for information on DPSGetCurrentContext().) Applications 
having more than one execution context can use the constant DPS_ALLCONTEXTS 
to trace all contexts belonging to them. 

The second argument, flag, determines whether tracing is enabled. If flag is YES, 
DPSTraceContextO chains a new context, known as the child context, to context, the 
parent context. (See “Chained Contexts” in the “Application Support” section of the 
Client Library Reference Manual.) The new context receives an ASCII version of the 
PostScript code that’s sent to the parent context. It also receives a copy of any values 
returned from the parent context to the client process. In the tracing output, values 
returned to the application are marked by the prepended string: 

% value returned ==> 

If flag is NO, the child context is unchained and destroyed. 
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For applications based on the Application Kit, there are two preferable methods for 
turning on tracing. You can use the NXShowPS command-line switch when you 
launch an application from Terminal. Alternatively, when you run the application 
under GDB, you can use the showps and shownops commands to control tracing 
output. 

Only one tracing context can be created for the supplied context. If you attempt to 
create additional tracing contexts for a context that’s already being traced, no new 
context is created and DPSTraceContext() returns -1. 


RETURN 

DPSTraceContext() returns 0 if successful in creating a tracing context, or -1 if not. 


DPSTraceEvents() 

SUMMARY Control debugging tracing of a context’s events 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/dpsclient.h> 

void DPSTraceEvents(DPSContext context, int flag) 

DESCRIPTION 

DPSTraceEvents() controls the tracing of events. When event tracing is enabled, 
information about each event that the application receives is sent to the UNIX standard 
error file, stderr. This information can be useful for program debugging and 
optimization. 

The first argument, context , specifies the context to be traced. An application’s single 
context can be returned with DPSGetCurrentContext(). (See the Client Library 
Reference Manual for information on DPSGetCurrentContext().) Applications 
having more than one execution context can use the constant DPS_ALLCONTEXTS 
to trace all contexts belonging to them. 

The second argument, flag, determines whether event tracing is enabled. If flag is YES, 
event tracing is enabled; if flag is NO, it’s disabled. 

When tracing is enabled and the application receives an event, the event record’s 
components are listed. For example, for a left mouse-down event the listing might look 
like this: 


Receiving: LMouseDown at: 343.0,69.0 time: 1271899 

flags: 0x0 win: 6 ctxt: 76128 data: 1111,1 
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The listing displays the fields of the event record: type, location, time, flags, local 
window number, PostScript execution context, and data. (See dpsclient/event.h for the 
structure of the event record.) The format of the data field listing depends on the event 
type; for instance, in the preceding example the event number and the click count were 


displayed. The following table lists the contents of the data field according to event 
type. 

Event Type 

NXJLMOUSEDOWN 

NXJLMOUSEUP 

NX_RMOUSEDOWN 

NX_RMOUSEUP 

Data 

data.mouse.eventNum, data.mouse.click 

NXJKEYDOWN 

NX_KEYUP 

data.key.repeat, data.key.charSet, 
data.key.charCode, data.key.keyCode, 
data.key.keyData 

NX_MOUSEENTERED 

NX_MOUSEEXITED 

data.tracking.eventNum, 

data.tracking.trackingNum, 

data.tracking.userData 

NX_MOUSEMOVED 
NX_LMOUSEDR AGGED 
NX_RMOUSEDRAGGED 
NX_FLAGSCHANGED 

And all other event types 

data.compound.subtype. 
data.compound.misc.L[0], 
data, compound. miscJL [ 1 ] 


For applications based on the Application Kit, there are two more convenient methods 
for turning on event tracing. You can use the NXTVaceEvents command-line switch 
when you launch an application from Terminal. Alternatively, when you run the 
application under GDB, you can use the traceevents and tracenoevents commands to 
control event-tracing output. 


DPSUndefineUserObjectQ —> See DPSDefineUserObjectQ 
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NXAllocErrorData(), NXResetErrorDataO 


SUMMARY Manage the error data buffer 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <objc/error.h> 

void NXAllocErrorData(int size, void **data) 
void NXResetErrorData(void) 

DESCRIPTION 

These functions handle the error buffer, which is used to pass error data to an error 
handler. When an error occurs, NX_RAISE() is called with two arguments that point 
to an arbitrary amount of data about the error. If an error handler can’t respond to the 
error, the error code and associated data are passed to the next higher-level handler. 

NXAllocErrorData() allocates size amount of space in the error buffer, increasing the 
size of the buffer if necessary. The data argument points to a pointer to the data in the 
buffer. To empty and free the buffer, call NXResetErrorDataO. If you’re using the 
Application Kit, the buffer is freed for you upon each pass through the event loop. 

SEE ALSO 

NX_RAISE(), NXDefaultTopLevelErrorHandler() 


NXAlphaComponent() —> See NXRedComponent() 
NXAtEOSO See NXSeekQ 


NXAttachPopUpList(), NXCreatePopUpListButton() 

SUMMARY Set up a pop-up list 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/appkit.h> 

void NXAttachPopUpList(id button, PopUpList popUpList ) 
id NXCreatePopUpListButton(PopUpList popUpList ) 
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DESCRIPTION 


These functions make it easy to use the PopUpList class, which is described in more 
detail in Chapter 3. NXCreatePopUpListButton() returns a new Button object that 
will activate the pop-up list specified by popUpList. 

NXAttachPopUpList() modifies button so that it activates popUpList. In addition, if 
button already has a target and an action, then they are used whenever a selection is 
made from the pop-up list. 

RETURN 

NXCreatePopUpListButtonQ returns a new Button object. 


NXBeepO 

SUMMARY Play the system beep 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/pub!icWraps.h> 

void NXBeep(void) 

DESCRIPTION 

This function plays the system beep. Users can select a sound to be played as the 
system beep through the Preferences application. 


NXBeginTimer(), NXEndTimer() 

SUMMARY Set up timer events 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/timer.h> 

NXTrackingTimer *NXBeginTimer(NXTrackingTimer *timer, double delay, 
double period) 

void NXEndTimer(NXTrackingTimer *timer) 
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DESCRIPTION 


These functions start up and end a timed entry that puts timer events in the event queue 
at specified intervals. They ensure that the modal event loop will get a stream of events 
even if none are being generated by the Window Server. 

NXBeginTimer()’s delay argument specifies the number of seconds after which timer 
events will begin to be added to the event queue; an event will then be added every 
period seconds. The first argument, timer, is a pointer to an NXTrackingTimer 
structure, which is defined in the header file appkit/timer.h. You don’t have to 
initialize this argument. If you pass a NULL pointer, memory will be allocated for the 
structure. Since timer events are usually needed only within a modal event loop, it’s 
generally better to declare the structure as a local variable on the stack. 

NXEndTimerO stops the flow of timer events. Its argument should be a pointer to the 
NXTrackingTimer structure used by NXBeginTimer(). If memory had been allocated 
for the structure, NXEndTimerO frees it. 

RETURN 

NXBeginTimer() returns a pointer to the NXTrackingTimer structure it uses. 


NXBlackComponentO —> See NXRedComponent() 
NXBlueComponentO -> See NXRedComponentO 
NXBPSFromDepthO —> See NXColorSpaceFromDepth() 
NXBrightnessComponent() -» See NXRedComponentO 
NXChangeAlphaComponentO —> See NXChangeRedComponentO 
NXChangeBlackComponentO —» See NXChangeRedComponentO 
NXChangeBlueComponentO —» See NXChangeRedComponentO 
NXChangeBrightnessComponent() —> See NXChangeRedComponentO 
NXChangeBufferO —> See NXStreamCreateO 
NXChangeCyanComponentO —> See NXChangeRedComponentO 
NXChangeGrayComponentO —> See NXChangeRedComponentO 
NXChangeGreenComponentO —> See NXChangeRedComponentO 
NXChangeHueComponentO -> See NXChangeRedComponentO 
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NXChangeMagentaComponent() —» See NXChangeRedComponent() 


NXChangeRedComponent(), NXChangeGreenComponent(), 
NXChangeBlueComponent(), NXChangeCyanComponentO, 
NXChangeMagentaComponent(), NXChangeYellowComponentO, 
NXChangeBIackComponentO, NXChangeHueComponentO, 
NXChangeSaturationComponentO, NXChangeBrightnessComponent(), 
NXChangeGrayComponent(), NXChangeAIphaComponent() 

SUMMARY Modify a color by changing one of its components 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

NXColor NXChangeRedComponent(NXColor color, float red) 

NXColor NXChangeGreenComponent(NXColor color, float green ) 

NXColor NXChangeBlueComponent(NXColor color, float blue) 

NXColor NXChangeCyanComponent(NXColor color, float cyan) 

NXColor NXChangeMagentaComponent(NXColor color, float magenta) 

NXColor NXChangeYellowComponent(NXColor color, float yellow) 

NXColor NXChangeBlackComponent(NXColor color, float black) 

NXColor NXChangeHueComponent(NXColor color, float hue) 

NXColor NXChangeSaturationComponent(NXColor color, float saturation) 
NXColor NXChangeBrightnessComponent(NXColor color, float brightness ) 
NXColor NXChangeGrayComponent(NXColor color, float gray) 

NXColor NXChangeAlphaComponent(NXColor color, float alpha ) 

DESCRIPTION 

These functions alter one component of a color value and return the new color. The first 
argument, color, is the color to be altered and the second argument is the new value for 
the altered component. For example, the code below specifies a color with a greater red 
content than the standard brown: 


NXColor redBrown = NXChangeRedComponent(NX_COLORBROWN, 0.9); 

Note that the color argument is used as a reference for creating a new color value; it is 
not itself changed. 

Values passed for the altered component should lie between 0.0 and 1.0; out-of-range 
values will be lowered to 1.0 or raised to 0.0. NX_NOALPHA can be passed to 
NXChangeAIphaComponent() to remove any specification of coverage from the 
color. 
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RETURN 


These functions return an NXColor structure that, except for the altered component, 
represents a color identical to the one passed as an argument. 

SEE ALSO 

NXRedComponentO, NXSetColor(), NXConvertRGBAToColor(), 
NXConvertColorToRGBAQ, NXEqualColorQ, NXReadColorQ 


NXChangeSaturationComponent() —» See NXChangeRedComponent() 
NXChangeYellowComponent() —> See NXChangeRedComponent() 
NXChunkCopyO —> See NXChunkMallocO 
NXChunkGrowQ —> See NXChunkMallocO 


NXChunkMallocO, NXChunkRealloc(), NXChunkGrowO, NXChunkCopyO, 
NXChunkZoneMallocO, NXChunkZoneReallocO, NXChunkZoneGrow(), 
NXChunkZoneCopyO 

SUMMARY Manage variable-sized arrays of records 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/chunk.h> 

NXChunk *NXChunkMalloc(int growBy, int initUsed) 

NXChunk *NXChunkRealloc(NXChunk *pc) 

NXChunk *NXChunkGrow(NXChunk *pc, int newUsed) 

NXChunk *NXChunkCopy(NXChunk *pc, NXChunk *dpc) 

NXChunk *NXChunkZoneMalloc(int growBy, int initUsed , NXZone *zone) 
NXChunk *NXChunkZoneRealloc(NXChunk *pc, NXZone *zone) 

NXChunk *NXChunkZoneGrow(NXChunk *pc, int newUsed, NXZone *zone) 
NXChunk *NXChunkZoneCopy(NXChunk *pc, NXChunk *dpc, NXZone *zone) 

DESCRIPTION 

A Text object uses these functions to manage variable-sized arrays of records. For 
general storage management, use objects of the Storage or List class. 

These functions are paired (for example, NXChunkZoneMallocO and 
NXChunkMallocO): One function lets you specify a zone and one doesn’t. Those 
functions that don’t take a zone argument operate within the default zone, as returned 
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by NXDefaultMallocZone(). In all other respects, the two types of functions are 
identical. In the following discussion, statements concerning one member of a function 
pair apply equally well to the other member. 

Arrays that are managed by these functions must have as their first element an 
NXChunk structure, as defined in appkit/chunk.h: 

typedef struct _NXChunk { 


short 

growby; 

/* 

Increment 

to grow by */ 

int 

allocated; 

/* 

Number of 

bytes allocated */ 

int 

used; 

/* 

Number of 

bytes used */ 

} NXChunk; 






For example, assuming an account structure has been declared, an accountArray 
structure is declared as: 

typedef struct _accountArray { 

NXChunk chunk; 
account record[1]; 

} accountArray; 

The NXChunk structure stores three values: growby specifies how many additional 
bytes of storage will be allocated when NXChunkRealloc() is called; allocated stores 
the number of bytes currently allocated for the array; and used stores the number of 
bytes currently used by the array’s elements. 

Note: The values recorded in the NXChunk element don’t take into account the size 
of the NXChunk element itself. However, the functions described here preserve space 
for this element. You don’t need to take into account the size of the array’s NXChunk 
when using these functions. 

Use NXChunkMalloc() to initially allocate memory for the array. The amount of 
memory allocated is equal to initUsed. If initUsed is 0, growby bytes is allocated. The 
array’s NXChunk element records the value of growby and the amount of memory 
allocated for the array. 

NXChunkRealloc() increases the amount of memory available for the array identified 
by the pointer pc. The amount of memory allocated depends on the value of the 
growby member of the array’s NXChunk element. If the value is 0, the space for 
elements is doubled; otherwise the array’s size increases by growby bytes. The 
allocated member of the array’s NXChunk element stores the new size of the array. 

NXChunkGrow() increases the size of the array identified by the pointer pc by a 
specific amount. The newUsed argument specifies the array’s new size in bytes. If the 
growby member of the array’s NXChunk element is 0, the array grows to the size 
specified by newUsed. Otherwise, the array grows to the larger of growby and 
newUsed. In either case, the size of the array changes only if the new size is larger than 
the old one. 
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NXChunkCopyO copies the array identified by the pointer pc to the array identified by 
the pointer dpc and returns a pointer to the copy. Since the new array may be relocated 
in memory, the returned pointer may be different than dpc. 

RETURN 

Each function returns a pointer to an array’s NXChunk element. NXChunkMalloc() 
returns a pointer to the newly allocated array, NXChunkRealloc() and 
NXChunkGrow() return pointers to the resized arrays, and NXChunkCopyO returns 
a pointer to the copy of the array. 


NXChunkRealloc() —> See NXChunkMaIIoc() 
NXChunkZoneCopyO —> See NXChunkMallocQ 
NXChunkZoneGrow() —> See NXChunkMalloc() 
NXChunkZoneMalloc() —» See NXChunkMallocO 
NXChunkZoneReallocQ —> See NXChunkMallocQ 


NXCloseO 

SUMMARY Close a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

void NXClose(NXStream * stream) 

DESCRIPTION 

This function closes the stream given as its argument. If the stream had been opened 
for writing, it’s flushed first. (The NXStream structure is defined in the header file 

stream/streams.h.) 

If the stream had been a file stream, the storage used by the stream is freed, but the file 
descriptor isn’t closed. See the UNIX manual page on close() for information about 
closing a file descriptor. If the stream had been on memory, the internal buffer is 
truncated to the size of the data in it. (Calling NXCloseO on a memory stream is 
equivalent to NXCloseMemoryO with the constant NX_TRUNCATEBUFFER.) 
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EXCEPTIONS 

NXClose() raises an NX_illegalStream exception if the stream passed in is invalid. 

SEE ALSO 

NXCloseMemoryO 

NXCloseMemoryO —> See NXOpenMemoryO 
NXCloseTypedStreamO -> See NXOpenTypedStream() 


NXCoIorSpaceFromDepth(), NXBPSFromDepth(), 
NXNumberOfColorComponentsO, NXGetBestDepth() 

SUMMARY Get information about color space and window depth 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

NXColorSpace NXColorSpaceFromDepth(NXWindowDepth depth ) 

int NXBPSFromDepth(NXWindowDepth depth ) 

int NXNumberOfCoIorComponents(NXColorSpace space ) 

BOOL NXGetBestDepth(NXWindowDepth * depth, int numColors, int bps) 

DESCRIPTION 

The first of these functions, NXCoIorSpaceFromDepth(), maps an enumerated value 
for window depth into the corresponding enumerated value for color space. The depth 
argument can be any of the following: 

NX_TwoB itGray Depth 
NX_EightB itGrayDepth 
NX_Twel veB itRGB Depth 
NXJTwentyFourB itRGB Depth 

The value returned will be one of the NXColorSpace values in this list: 

NX_OneIsBlackColorSpace 

NX_OneIsWhiteColorSpace 

NX_RGBColorSpace 

NX_CMYKColorSpace 
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NX_TwoBitGrayDepth and NX_EightBitGrayDepth map to 
NX_OneIs WhiteColorSpace. 

The second function, NXBPSFromDepth(), extracts the number of bits per sample 
(bits per pixel in each color component) from a window depth. 

The third function, NXNumberOfColorComponents(), similarly extracts the number 
of color components from a color space. The value returned will be 1,3, or 4. 

The fourth function, NXGetBestDepth(), finds the best window depth for an image 
with a given number of color components, numColors, and a given bits per sample, bps. 
The depth is returned by reference in the variable specified by depth. It will be one of 
the enumerated values listed above. If the depth provided exactly matches the 
requirements of numColors and bps , or is deeper than required, this function returns 
YES. If the depth isn’t deep enough for numColors and bps, but is the best available, 
it returns NO. 

RETURN 

NXColorSpaceFromDepthO returns the color space that matches a given window 
depth. NXBPSFromDepthO returns the number of bits per sample for a given window 
depth. NXNumberOfColorComponentsO returns the number of color components in 
a given color space. NXGetBestDepth() returns YES if it can provide a window depth 
deep enough for numColors and bps, and NO if it can’t. 


NXCompareHashTablesQ —» See NXCreateHashTableO 
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NXCompleteFilename() 

SUMMARY Match an incomplete filename 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/SavePaneI.h> 

int NXCompleteFileriame(char *path , int maxPathSize ); 

DESCRIPTION 

NXCompleteFilename is used by the SavePanel class to determine the number of files 
matching an incomplete pathname, path is a pointer to a buffer containing an 
incomplete pathname. maxPathSize is the size of the buffer, not the length of path as 
determined by strlen (path). 

RETURNS 

This function returns the number of files that match the incomplete name. By 
reference, path returns up to maxPathSize characters of the path to the first file matching 
the incomplete name. 


NXContainsRectO —> See NXMouseInRect() 
NXConvertCMYKAToColor() -a See NXConvertRGBAToColor() 
NXConvertCMYKToColor() —> See NXConvertRGBAToColor() 
NXConvertColorToCMYKO -> See NXColorToRGBA() 
NXConvertColorToCMYKAO —> See NXCoIorToRGBA() 
NXConvertColorToGrayO -a See NXColorToRGBA() 
NXConvertColorToGrayAlpha() -A See NXColorToRGBA() 
NXConyertColorToHSBQ -a See NXColorToRGBA() 
NXConvertColorToHSBAO -a See NXColorToRGBA() 
NXConvertColorToRGB() -a See NXColorToRGBAQ 
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NXConvertColorToRGBAQ, NXConvertColorToCMYKA(), 
NXConvertColorToHSBAO, NXConvertColorToGrayAlpha(), 
NXConvertColorToRGBO, NXConvertColorToCMYK(), 
NXConvertColorToHSBO, NXConvertColorToGrayO 

SUMMARY Convert a color value to its standard components 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

void NXConvertColorToRGBA(NXColor color , float *red , float * green, float *blue, 
float *alpha) 

void NXConvertColorToCMYKA(NXColor color, float *cyan, float *magenta, 
float *yellow, float *black, float * alpha) 
void NXConvertColorToHSBA(NXColor color, float *hue, float * saturation, 
float * brightness, float *alpha) 

void NXConvertColorToGrayAlpha(NXColor color, float *gray, float * alpha) 
void NXConvertColorToRGB(NXColor color, float *red, float * green, float *blue) 
void NXConvertColorToCMYK(NXColor color, float *cyan, float *magenta, 
float *yellow, float *black) 

void NXConvertColorToHSB(NXColor color, float *hue, float * saturation, 
float * brightness ) 

void NXConvertColorToGray(NXColor color, float *gray) 

DESCRIPTION 

These functions convert a color value, color, to its standard components. The first 
argument to each function is the NXColor data structure to be converted. Subsequent 
arguments point to float variables where the component values can be returned by 
reference. 

The conversion can be to any set of components that might be used to specify a color 
value: 

• Red, green, and blue (RGB) components 

• Cyan, magenta, yellow, and black (CMYK) components 

• Hue, saturation, and brightness (HSB) components 

• A single component for gray scale images 

A color initially specified by one set of components can be converted to another set. For 
example: 

NXColor color; 

float hue, saturation, brightness; 

color = NXConvertRGBToColor(0.8, 0.3, 0.15); 

NXConvertColorToHSB(color, &hue, &saturation, Sbrightness); 


NXConvertColorToRGBA() 3-33 



The first four functions in the list above report the coverage component, alpha, included 
in the color value, as well as the color components. The second four report only the 
color components; they’re macros and are defined on the corresponding functions, but 
ignore the alpha argument. 

The float values returned by reference will lie in the range 0.0 through 1.0. The value 
returned for the coverage component will be NX_NOALPHA if color doesn’t include 
a coverage specification. 

SEE ALSO 

NXConvertRGBAToColorO, NXSetColor(), NXEqualColor(), 
NXRedComponentO, NXChangeRedComponent(), NXReadColorQ 


NXConvertGIobalToWinNumO —» See NXConvertWinNumToGIobal () 
NXConvertGrayAlphaToColor() —> See NXConvertRGBAToColorO 
NXConvertGrayToColor() —> See NXConvertRGBAToColorO 
NXConvertHSBAToColor() -a See NXConvertRGBAToColorO 
NXConvertHSBToColor() -> See NXConvertRGBAToColorO 
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NXConvertRGBAToColorO, NXConvertCMYKAToColor(), 
NXConvertHSBAToColor(), NXConvertGrayAlphaToColor(), 
NXConvertRGBToCoIorO, NXConvertCMYKToColor(), 
NXConvertHSBToColorO, NXConvertGrayToColor() 

SUMMARY Specify a color value 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

NXColor NXConvertRGBAToColor(float red, float green, float blue, float alpha) 
NXColor NXConvertCMYKAToColor(float cyan, float magenta, float yellow, 
float black, float alpha) 

NXColor NXConvertHSBAToCoIor(float hue, float saturation, float brightness, 
float alpha) 

NXColor NXConvertGrayAIphaToColor(float gray, float alpha) 

NXColor NXConvertRGBToColor(float red, float green, float blue) 

NXColor NXConvertCMYKToCoior(float cyan, float magenta, float yellow, 
float black) 

NXColor NXConvertHSBToCoIor(float hue, float saturation, float brightness) 
NXColor NXConvertGrayToColor(float gray) 

DESCRIPTION 

These functions specify a color by its standard components and return an NXColor 
structure for the color. In the Application Kit, a color can be specified in any of four 
ways: 

• By its red, green, and blue components (RGB) 

• By its cyan, magenta, yellow, and black components (CMYK) 

• By its hue, saturation, and brightness components (HSB) 

• On a gray scale 

No matter how they’re specified, all color values are stored as the NXColor data type. 
The internal format of this type is unspecified; it should be set only through these 
functions or as one of the constants defined for pure colors, such as 
NX_COLORORANGE or NX_COLORWHITE. 

The NXColor structure includes provision for a coverage component, alpha, which can 
be specified at the same time as the color. The first four functions listed above specify 
both color and coverage. The last four specify only color; they’re defined as macros 
that work through the corresponding functions by passing NX_NOALPHA for the 
alpha argument. 

Except for NX_NOALPHA, all values passed for color and coverage components 
should lie in the range 0.0 through 1.0; higher values will be reduced to 1.0 and lower 
ones raised to 0.0. 
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RETURN 


Each of these functions and macros returns an NXColor structure for the color 
specified. 

SEE ALSO 

NXConvertCoIorToRGBAO, NXSetColor(), NXEqualColor(), 
NXRedComponent(), NXChangeRedComponentQ, NXReadColorQ 


NXConvertRGBToColor() See NXConvertRGBAToColor() 


NXConvertWinNumToGlobalO, NXConvertGIobalToWinNum () 

SUMMARY Convert local and global window numbers 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/ pubIicWraps.h> 

void NXConvertWinNumToGlobal(int winNum, unsigned int *globalNum ) 
void NXConvertGlobaIToWinNum(int globalNum , unsigned int *winNum ) 

DESCRIPTION 

These functions allow two or more applications to refer to the same window. In the rare 
cases where this is necessary, the global window number, which has been automatically 
assigned by the Window Server, is used rather than the local window number, which is 
assigned by the application. 

NXConvertWinNumToGlobalO takes the local window number and places the 
corresponding global window number in the variable specified by globalNum. This 
global number can then be passed to other applications that need to access the window. 
To convert window numbers in the opposite direction, give the global number as an 
argument for NXConvertGIobaIToWinNum(); this function places the appropriate 
local number in the variable specified by winNum. 
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NXCopyBitsO 


SUMMARY Copy an image 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXCopyBits(int gstate, NXRect *aRect, const NXPoint *aPoint ) 
DESCRIPTION 

NXCopyBitsO uses the composite operator to copy the pixels in the rectangle specified 
by aRect to the location specified by aPoint. 

The source rectangle is defined in the graphics state designated by the gstate user 
object. If gstate is NXNullObject, the current graphics state is assumed. 
NXNullObject is declared in appkit/Application.h. 

The aPoint destination is defined in the current graphics state. 

SEE ALSO 

composite operator 


NXCopyCurrentGStateO -> See NXSetGStateQ 
NXCopyHashTableQ —> See NXCreateHashTableO 
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NXCopylnputDataQ, NXCopyOutputDataO 


SUMMARY Save data received in a remote message 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/ Listener.h> 

char *NXCopyInputData(int parameter ) 
char *NXCopyOutputData(int parameter) 

DESCRIPTION 

These functions each return a pointer to memory containing data passed from one 
application to another in a remote message. NXCopyInputData() is used for data 
received by a Listener object, and NXCopyOutputDataO is used for return data 
received back by a Speaker. 

Data received by a Listener in a remote message is guaranteed only for the duration of 
the receiving application’s response to the message. Return data passed back to a 
Speaker is guaranteed only until the Speaker receives another return message. 
Therefore, you must copy any data you wish to keep. 

If the data is passed in-line (if it’s not too large to fit within the Mach message), these 
functions allocate memory for the data, copy it, and return a pointer to the copy. 
However, it’s likely that more memory will be allocated than is required for the copy. 
Both functions use vm_allocate(), which provides memory in multiples of a page. 

Therefore, for in-line data, it’s more efficient for you to allocate the memory yourself, 
using malloc() or NX_MALLOC(), then copy the data using a standard library 
function like strcpy(). 

For out-of-line data (data that’s too large to fit within the Mach message itself, so that 
only a pointer to it is passed), it’s generally more efficient to use NXCopyInputData() 
and NXCopyOutputDataO to save a copy. Both functions ensure that the Listener or 
Speaker won’t free the out-of-line data. Both return a pointer to the data without 
actually copying it. 

The memory returned by these functions should be freed using vm_dealIocate(), rather 
than free(). 

The data to be saved is identified by parameter , an index into the list of parameters 
declared for the Objective-C method that sends or receives the remote message. Indices 
begin at 0, and byte arrays count as a single parameter even though they’re declared as 
a combination of a pointer to the array and an integer that counts the number of bytes 
in the array. 

The examples below illustrate how these these functions are used. In the first, a 
Listener receives a translateGaeIic::toWelsh::ok: message, a fictitious message 
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which requests the receiving application to exchange Gaelic text for the equivalent 
Welsh version. If the application needs to save the original text, it would copy it, using 
NXCopyInputData(), in the method it implements to respond to the message: 

char *originalText; 

- (int)translateGaelic:(char *)gaelicText 
:(int)gaelicLength 
toWelsh:(char *)welshText 
:(int *)welshLength 
ok:(int *)flag 

{ 

if ( gaelicLength >= vm_page_size ) 

originalText = NXCopylnputData(0); 


} 

The application that sends a translateGaelic::toWelsh::ok: message would save the 
returned text, using NXCopyOutputData(), immediately after sending the remote 
message: 

char , *newText; 

int newLength; 

int error, success; 

error = [mySpeaker translateGaelic:someText 

:strlen(someText) 
toWelsh:SnewText 
:SnewLength 
ok:Ssuccess]; 
if ( lerror && success ) 

newText = NXCopyOutputData(1); 


RETURN 

Both functions return a pointer to memory containing data identified by the parameter 
index, or a NULL pointer if the data can’t be provided. 


NXCopyOutputData() —> See NXCopyInputData() 
NXCopyStringBuffer() —> See NXUniqueStringO 
NXCopyStringBufferFromZone() —> See NXUniqueStringO 
NXCountHashTable() —> See NXHashlnsertQ 
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NXCountWindowsO, NXWindowListO 


SUMMARY Get information about an application’s windows 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/publicWraps.h> 

void NXCountWindows(int *count ) 
void NXWindowList(int size, int /«*[]) 

DESCRIPTION 

NXCountWindowsO counts the number of on-screen windows belonging to the 
application; it returns the number by reference in the variable specified by count. 

NXWindowListO provides an ordered list of the application’s on-screen windows. It 
fills the list array with up to size window numbers; the order of windows in the array is 
the same as their order in the Window Server’s screen list (their front-to-back order on 
the screen). Use the count obtained by NXCountWindowsO to specify the size of the 
array for NXWindowListO. 


NXCreateChildZoneO -> See NXZoneMallocQ 


Chapter 3: C Functions 



NXCreateHashTable(), NXCreateHashTableF romZone(), 

NXFreeHashTableQ, NXEmptyHashTableO, NXResetHashTableO, 
NXCopyHashTable(), NXCompareHashTables(), NXPtrHash(), NXStrHash(), 
NXPtrlsEqualO, NXStrIsEqual(), NXNoEffectFreeQ, NXReallyFree() 

SUMMARY Create and free a hash table 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/hashtable.h> 

NXHashTable *NXCreateHashTable(NXHashTablePrototype prototype, 
unsigned capacity, const void *info) 

NXHashTable *NXCreateHashTableFromZone(NXHashTablePrototype prototype, 
unsigned capacity, const void *info, NXZone *zone) 
void NXFreeHashTable(NXHashTable * table) 
void NXEmptyHashTable(NXHashTable *table) 
void NXResetHashTable(NXHashTable * table) 

NXHashTable *NXCopyHashTable(NXHashTable *table) 

BOOL NXCompareHashTables(NXHashTable * table 1, NXHashTable * table!) 

unsigned NXPtrHash(const void *info, const void *data) 

unsigned NXStrHash(const void *info, const void *data) 

int NXPtrIsEqual(const void *info, const void *datal, const void *data2) 

int NXStrIsEqual(const void *info, const void *datal, const void *data2) 

void NXNoEffectFree(const void *info, void *data) 

void NXReallyFree(const void *info, void *data) 

DESCRIPTION 

These functions set up, copy, and free a hash table. A hash table provides an efficient 
means of manipulating elements of an unordered set of data. A data element is stored 
by computing a hash function—or hashing—on the element to be stored. The value of 
the hashing function, sometimes called the key, is used to determine the location at 
which to store the data. The functions described under NXHashInsert() insert, 
remove, and search for a data element; they also count the number of elements and 
iterate over all elements in a hash table. 

To create a hash table, call NXCreateHashTable() or 

NXCreateHashTableFromZone(). These functions differ only in that the first one 
creates the hash table in the default zone, as returned by NXDefaultMalIocZone(), and 
the second lets you specify a zone. Only NXCreateHashTable() will be discussed 
below. 
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The first argument to NXCreateHashTabIe() is a NXHashTablePrototype structure, 
which is defined in objc/hashtable.h and shown below. This structure requires you to 
specify three functions, a hashing function, a comparison function that determines 
whether two data elements are equal, and a freeing function that frees a given data 
element in the table: 

typedef struct { 

unsigned (*hash)(const void *info, const void *data); 
int (*isEqual) (const void *info, const void *datal, 

const void *data2); 

void (*free) (const void *info, void *data); 

int style; 

} NXHashTablePrototype; 

The hashing function must be defined such that if two data elements are equal, as 
defined by the comparison function, the values produced by hashing on these elements 
must also be equal. Also, data elements must remain invariant if the value of the 
hashing function depends on them; for example, if the hashing function operates 
directly on the characters of a string, that string can’t change. The comparison function 
must return true if and only if the two data elements being compared are equal. The 
third function specifies how a data element is to be freed. The style field is reserved for 
future use; currently, it should be passed in as 0. 

As shown, the third argument for NXCreateHashTable(), info , is passed as the first 
argument to the hashing, comparison, and freeing functions. You can use info to 
modify or add to the effects produced by these functions. For example, the comparison 
function can be modified to return a certain value if the elements being compared are 
similar to each other but not exactly equal. 

For convenience, functions for hashing pointers, integers, and strings and for 
comparing them have already been defined; two different freeing functions are also 
provided. NXPtrHash() hashes the address bits of data and returns a key for storing 
the data. NXPtrlsEqualQ returns nonzero if datal is equal to data2 and 0 if they’re 
not equal. These functions can be used for pointers or for data of type int. Similarly, 
NXStrHash() returns a key for the string passed in as data, and NXStrIsEqual() 
checks whether two strings are equal. NXReallyFreeO frees the data element passed 
in, allowing its key to be reused. NXNoEffectFreeO, as its name implies, has no effect. 

The info argument for all six of these functions isn’t used. If you want to hash data 
other than pointers or strings, or if you want to use the info argument, you need to write 
your own hashing, comparison, and freeing functions. 
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In addition to the hashing, comparison, and freeing functions, four different prototypes 
have been predefined. The prototype for pointers (which can also be used for data of 
type int) and the one for strings both use the functions described above: 


const NXHashTablePrototype NXPtrPrototype = { 
NXPtrHash, NXPtrlsEqual, NXNoEffectFree, 0 

}; 

const NXHashTablePrototype NXStrPrototype = { 
NXStrHash, NXStrlsEqual, NXNoEffectFree, 0 

} ; 


The following example shows how to use NXPtrPrototype to create a hash table for 
storing a set of pointers or data of type int: 


NXHashTable *myHashTable; 

myHashTable = NXCreateHashTable(NXPtrPrototype, 0, NULL); 


Note that you pass the NXPtrPrototype structure as an argument, not a pointer to it. 
NXCreateHashTable() returns a pointer to an NXHashTable structure, which is 
defined in the header file objc/hashtable.h. 

The other two prototypes create a hash table for storing a set of structures; the first 
element of each structure will be used as the key. NXPtrStructKeyPrototype expects 
the first element to be a pointer, and NXStrStructKeyPrototype expects a string. The 
free function for both these prototypes is NXReallyFree(). 

NXCreateHashTableO’s second argument, capacity, is only a hint; you can just pass 
0 to create a minimally sized table. As more space is needed, it will be automatically 
and efficiently allocated. 

NXFreeHashTable() frees each element of the specified hash table and the table itself. 
NXResetHashTable() frees each element but doesn’t deallocate the table. This is 
useful for retaining the table’s capacity. NXEmptyHashTable() sets the number of 
elements in the table to 0 but doesn’t deallocate the table or the data in it. 

NXCopyHashTableQ returns a pointer to a copy of the hash table passed in. 
NXCompareHashTables() returns YES if the two hash tables supplied as arguments 
are equal. That is, each element of tablel is in table 2, and the two tables are the same 
size. 


NXCreateHasKFable() 
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RETURN 

NXCreateHashTable(), NXCreateHashTableFromZone(), and 
NXCopyHashTableO return pointers to the new hash tables they create. 

NXCompareHashTables() returns YES if the two hash tables supplied as arguments 
are equal. 

NXPtrHash() returns a key for storing a pointer in a hash table; NXStrHash() returns 
a key for storing a string. 

NXPtrIsEqual() and NXStrIsEquaI() return nonzero if the two data elements passed 
in are equal, and 0 if they’re not. 

SEE ALSO 

NXHashlnsertQ 


NXCreateHashTableFromZoneO -> See NXCreateHashTableQ 
NXCreatePopUpListButton() —» See NXAttachPopUpListO 
NXCreateZoneO -> See NXZoneMaIIoc() 
NXCyanComponent() —> See NXRedComponent() 


NXDefaultExceptionRaiser(), NXSetExceptionRaiser(), 
NXGetExceptionRaiser() 

SUMMARY Set and return an exception raiser 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <objc/error.h > 

void NXDefaultExceptionRaiser(int code , const void *datal, const void *data2) 
void NXSetExceptionRaiser(NXExceptionRaiser * procedure ) 
NXExceptionRaiser *NXGetExceptionRaiser(void) 
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DESCRIPTION 


These functions set and return the procedure that’s called when exceptions are raised 
using NX_RAISE(). By default, the NXDefaultExceptionRaiser() will be invoked by 
NX_RAISE(); this function is also what NXGetExceptionRaiser() returns unless 
you’ve declared your own exception raiser by using NXSetExceptionRaiser(), as 
described below. 

NXDefaultExceptionRaiser() forwards the exception condition indicated by code and 
any information about the exception pointed to by datal and data2 to the next error 
handler. Error handlers exist in a nested hierarchy, which is created by using any 
number of nested NX_DURING...NX_ENDHANDLER constructs and by defining a 
top-level error handler. 

If the error has occurred outside of the domain of any handler, 
NXDefaultExceptionRaiser() invokes an uncaught exception handling function. For 
more information on the Application Kit’s default uncaught exception handling 
function or to define your own, see the description of 

NXSetUncaughtExceptionHandIer(). If the uncaught exception handling function 
can’t be found, NXDefaultExceptionRaiser() exits. 

To override the default exception raiser, call NXSetExceptionRaiser() and give it a 
pointer to the exception raising function you want to use. This function must be of type 
NXExceptionRaiser (that is, the same type as NXDefaultExceptionRaiserO), which 
is defined in the header file streams/error.h as follows: 

typedef void NXExceptionRaiser(int code, const void *datal, 
const void *data2); 


In other words, the function procedure must take three arguments of the types shown 
above, and it must return void. Once you’ve called NXSetExceptionRaiser(), 
subsequent calls to NXGetExceptionRaiser() will return a pointer to procedure; also, 
subsequent calls to NX_RAISE() will invoke procedure. 

SEE ALSO 

NX_RAISEQ, NXSetUncaughtExceptionRaiser() 


NXDefaultMallocZone() —> See NXZoneMalloc() 
NXDefaultRead() —> See NXStreamCreate() 
NXDefaultStringOrderTable() —> See NXOrderStringsQ 


NXDefaultExceptionRaiser() 


3-45 



NXDefauItTopLevelErrorHandler(), NXSetTopLevelErrorHandler(), 
NXTopLevelErrorHandler() 

SUMMARY Define an error handler 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/errors.h> 

void NXDefauItTopLeveIErrorHandler(NXHandler *errorState ) 
NXTopLevelErrorHandler 

*NXSetTopLevelErrorHandler(NXTopLevelErrorHandler * procedure) 
NXTopLevelErrorHandler *NXTopLevelErrorHandler(void) 

DESCRIPTION 

This group of a function and two macros defines the top-level error handler. The 
top-level handler is called when an exception is forwarded through the nested 
lower-level handlers up to the top level. The hierarchy of error handlers is created by 
using any number of nested NX_DURING...NX_ENDHANDLER constructs. 

If an application doesn’t define its own top-level handler, by default it will use 
NXDefaultTopLevelErrorHandler(). This function is defined and used by the 
Application Kit. Its only argument is a pointer to an NXHandler structure, which is 
defined in the header file streams/error.h. This file also defines 
NXDefaultTopLevelErrorHandler() as being a global variable of type 
NXTopLevelErrorHandler, which is defined as follows: 

typedef void NXTopLevelErrorHandler(NXHandler *errorState); 
extern NXTopLevelErrorHandler NXDefaultTopLevelErrorHandler; 


NXDefaultTopLevelErrorHandler () calls NXReportError(), which executes the 
procedure defined to report the error that occurred. (See the description of 
NXRegisterErrorReporter() in this chapter for details about NXReportError().) If 
an error occurred when an application’s PostScript context was created or if its 
PostScript connection is broken, NXDefaultTopLevelErrorHandler() exits. 

An application can override NXDefaultTopLevelErrorHandler() by defining its own 
top-level handler. This involves passing a pointer to an error-handling procedure to the 
macro NXSetTopLeveIErrorHandler(). The new error-handling procedure must be 
of type NXTopLevelEirorHandler, which means it must take a pointer to an NXHandler 
as its only argument and it must return void. 

NXTopLevelErrorHandIer() returns a pointer to the current top-level handler. After 
a new one has been set using NXSetTopLeveIErrorHandler(), subsequent calls to 
NXTopLevelErrorHandlerQ will return a pointer to the new top-level error handler. 
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The two macros, NXSetTopLevelErrorHandlerO and NXTopLevelErrorHandler(), 
are defined in the header file appkit/errors.h. 

SEE ALSO 

NX_RAISE(), NXDefaultExceptionRaiser(), NXRegisterErrorReporter() 

NXDefaultWrite() -a See NXStreamCreate() 

NXDestroyZoneO -> See NXZoneMalloc() 

NXDivideRectO -> See NXSetRectO 
NXDrawALineQ —> See NXScanALineQ 


NXDrawButton(), NXDrawGrayBezel(), NXDrawGroove(), 
NXDrawWhiteBezel(), NXDrawTiledRectsO, NXFrameRect(), 

NXF rameRectWith Width() 

SUMMARY Draw a bordered rectangle 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXDrawButton(const NXRect *aRect, const NXRect *clipRect) 
void NXDrawGrayBezel(const NXRect *aRect, const NXRect *clipRect) 
void NXDrawGroove(const NXRect *aRect, const NXRect *clipRect) 
void NXDrawWhiteBezel(const NXRect *aRect, const NXRect *clipRect ) 

NXRect *NXDrawTiledRects(NXRect *aRect, const NXRect *clipRect , 
const int * sides, const float * grays, int count ) 
void NXFrameRect(const NXRect *aRect) 

void NXFrameRectWithWidth(const NXRect *aRect, NXCoord frameWidth) 
DESCRIPTION 

These functions draw rectangles with borders. NXDrawButton() draws the rectangle 
used to signify a button on a NeXT computer, NXDrawTiledRectsO is a generic 
function that can be used to draw different types of borders, and the other functions 
provide ready-made bezeled, grooved, or line borders. These borders can be used to 
outline an area or to give rectangles the effect of being recessed from or elevated above 
the surface of the screen, as shown in Figure 3-1. 
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Figure 3-1. Rectangle Borders 


Each function’s first argument specifies the rectangle within which the border is to be 
drawn in the current coordinate system. Since these functions are often used to draw 
the border of a View, this rectangle will typically be that View’s bounds rectangle. 
Some of the functions also take a clipping rectangle; only those parts of aRect that lie 
within the clipping rectangle will be drawn. 

As its name suggests, NXDrawWhiteBezelQ fills in its rectangle with white; 
NXDrawButtonO, NXDrawGrayBezelQ, and NXDrawGroove() use light gray. 
These functions are designed for rectangles that are defined in unsealed, unrotated 
coordinate systems (that is, where the y-axis is vertical, the x-axis is horizontal, and a 
unit along either axis is equal to one screen pixel). The coordinate system can be either 
flipped or unflipped. The sides of the rectangle should lie on pixel boundaries. 

NXFrameRectO and NXFrameRectWithWidth() draw a frame around the inside of 
a rectangle in the current color. NXFrameRectO draws a frame with a width equal to 
1.0 in the current coordinate system; NXFrameRectWithWidth() allows you to set the 
width of the frame. Since the frame is drawn inside the rectangle, it will be visible even 
if drawing is clipped to the rectangle (as it would be if the rectangle were a View 
object). These functions work best if the sides of the rectangle lie on pixel boundaries. 

In addition to its aRect and clipRect arguments, NXDrawTiledRects() takes three 
more arguments, which determine how thick the border is and what gray levels are used 
to form it. NXDrawTiledRectsQ works through NXDivideRectO to take successive 
1.0 unit-wide slices from the sides of the rectangle specified by the sides argument. 
Each slice is then drawn using the corresponding gray level from grays. 
NXDrawTiledRectsO makes and draws these slices count number of times. 
NXDivideRectO returns a pointer to the rectangle after the slice has been removed; 
therefore, if a side is used more than once, the second slice is made inside the first. This 
also makes it easy to fill in the rectangle inside of the border. 
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In the following example, NXDrawTiledRects() draws a bezeled border consisting of 
a 1.0 unit-wide white line at the top and on the left side, and a 1.0 unit-wide dark-gray 
line inside a 1.0 unit-wide black line on the other two sides. The rectangle inside this 
border is filled in using light gray. 

int mySides[] = {NX_YMIN, NX_XMAX, NX_YMAX, NX_XMIN, 

NX_YMIN, NX_XMAX}; 

float myGrays[] = {NX_BLACK, NX_BLACK, NX_WHITE, NX_WHITE, 

NX_DKGRAY, NX_DKGRAY}; 

NXRect *aRect; 

NXDrawTiledRects(aRect, (NXRect *)0, mySides, myGrays, 6); 

PSsetgray(NX_LTGRAY); 

PSrectfill(aRect->origin.x, aRect->origin.y, 

aRect->size.width, aRect->size.height); 


As shown, mySides is an array that specifies sides of a rectangle; for example, 
NX_YMIN selects the side parallel to the x-axis with the smallest y-coordinate value. 
The constants shown in mySides are described in more detail in the description of 
NXDivideRect(). myGrays is an array that specifies the successive gray levels to be 
used in drawing parts of the border. 

RETURN 

NXDrawTiledRects() returns a pointer to the rectangle that lies within the border. 

SEE ALSO 

NXDivideRectQ 


NXDrawGrayBezel() —> See NXDrawButton() 
NXDrawGrooveO —> See NXDrawButton() 
NXDrawTiIedRects() -> See NXDrawButton() 
NXDrawWhiteBezel() —> See NXDrawButton() 
NXEditorFilter() -> See NXFieldFilter() 
NXEmptyHashTableO See NXCreateHashTable() 
NXEmptyRect() -> See NXMouselnRectQ 
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NXEndOfTypedStreamO 


SUMMARY Determine whether there’s more data to be read 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

BOOL NXEndOfTypedStream(NXTypedStream *typedStream) 

DESCRIPTION 

This macro indicates whether more data is available to be read from the typed stream 
passed in as an argument. It should be called only on a typed stream opened for 
reading. (The NXTypedStream type is declared in the header file objc/typedstream.h. 
The structure itself is private since you never need to access its members.) 

RETURN 

NXEndOfTypedStreamO returns TRUE if more data is available to be read and 
FALSE otherwise. 

EXCEPTIONS 

NXEndOfTypedStreamO raises a TYPEDSTREAM_CALLER_ERROR with the 
message “expecting a reading stream” if the stream passed in wasn’t opened for 
reading. 

SEE ALSO 

NXOpenTypedStream() 


NXEndTimer() —> See NXBeginTimer() 

NXEqualCoIorO 

SUMMARY Test whether two colors are the same 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/co!or.h> 

BOOL NXEquaIColor(NXColor oneColor, NXColor anotherColor ) 
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DESCRIPTION 


This function compares oneColor to anotherColor and returns YES if they are, in fact, 
the same color. Two colors can be the same, yet be represented differently within the 
NXColor structure. Therefore, NXColor structures should be compared only through 
this function, never directly. 

The coverage components of the NXColor structures are included in the comparison. 
RETURN 

This function returns YES if the two colors are visually identical, and NO if they’re not. 
SEE ALSO 

NXSetColor(), NXConvertRGBAToColor(), NXConvertColorToRGBA(), 
NXRedComponentQ, NXChangeRedComponentQ, NXReadColorQ 


NXEqualRect() —> See NXMouselnRectO 
NXEraseRectQ See NXRectClipO 
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NXFieldFilterQ, NXEditorFilterQ 


SUMMARY Filter characters entered into Text object 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Text.h> 

unsigned short NXFieldFilter(unsigned short theChar, int flags, 
unsigned short charSet ) 

unsigned short NXEditor Filter (unsigned short theChar, int flags, 
unsigned short charSet ) 

DESCRIPTION 

These functions check each character the user types into a Text object’s text. Use 
NXFieldFilter(), the Text object’s default character filter, when you want the user to be 
able to move the selection from text field to field by pressing Return, Tab, or Shift-Tab. 
Use NXEditorFilter() when you don’t want Return, Tab, and Shift-Tab interpreted in 
this way. 

NXFieldFilter() passes on values generated by alphanumeric keys directly to the Text 
object for display. Values generated by Return, Tab, Shift-Tab, and the arrow keys are 
remapped to constants that have a special meaning for the Text object. The Text object 
interprets any of these constants as a movement command, a command to end the Text 
object’s status as first responder. Based on the key pressed, the Text object’s delegate 
can control which other object should become the first responder. NXFieldFilter() 
remaps to 0 all other values less than 0x20 and any values generated in conjunction with 
the Command key. 

NXEditorFilter() is identical to NXFieldFilter() except that it passes on values 
corresponding to Return, Tab, and Shift-Tab directly to the Text object. 

RETURN 

NXFieldFilter() returns 0 (NX_ILLEGAL), the ASCII value of the character typed, or 
a constant the Text object interprets as a movement command. The constants are: 

NX_RETURN 

NX_TAB 

NXJBACKTAB 

NX__LEFT 

NX_RIGHT 

NX_UP 

NXJDOWN 

This function also returns 0 if a key is pressed while a Command key is held down. 
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NXEditorFilter()’s return values are identical to those of NXFieldFilter(), except that 
it also returns the values generated by Return, Tab, and Shift-Tab without first 
remapping them. 


NXFilePathSearch() 

SUMMARY Search for and read a file 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/defaults.h> 

#import <defaults.h> 

int NXFilePathSearch(const char *envVarName, const char *defaultPath, 
int leftToRight, const char *fileName, int ( *funcPtr)( ), void *funcArg ) 

DESCRIPTION 

NXFilePathSearch() searches a colon-separated list of directories for one or more files 
named fileName. The directory list is obtained from the environmental variable, 
envVarName, if it’s available. If not, defaultPath is used. If leftToRight is true, the list 
of directories is searched from left to right; otherwise, it’s searched right to left. 

In each directory, if the file fileName can be accessed, the function specified by funcPtr 
is called. The function is passed two arguments, the path to the file mdfuncArg, which 
can contain arbitrary data for the function to use. 

RETURN 

If the function specified by funcPtr is called and returns 0 or a negative value, 
NXFilePathSearch() returns the same value. If the function returns a positive value, 
NXFilePathSearch() continues searching through the directory list for other 
occurrences of fileName. If it searches through the entire directory list, it returns 0. If 
it can’t find a list of directories to search, it returns -1. 


NXFillO -> See NXStreamCreateO 


NXFilePathSearch() 
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NXFindPaperSizeO 


SUMMARY Find dimensions of specified paper type 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/PageLayout.h> 

const NXSize *NXFindPaperSize(const char *paperName ) 

DESCRIPTION 

NXFindPaperSizeO returns a pointer to an NXSize structure containing the 
dimensions of a sheet of paper of type paperName. The dimensions are given in points 
(72 per inch). The NXSize structure is defined in the header file dpsclient/event.h as 
follows: 

typedef struct _NXSize { 

NXCoord width; 

NXCoord height; 

} NXSize; 

paperName is a character string that corresponds to one of the standard paper types 
used by conforming PostScript documents. For example, it could be “Letter”, “Legal”, 
or “A4”. By providing the precise size of these types, this function helps programs 
adjust the on-screen display to the page size of the document being displayed. 

RETURN 

This function returns an NXSize pointer. 
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NXFlushQ 


SUMMARY Flush a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 
int NXFlush(NXStream * stream) 

DESCRIPTION 

This function flushes the buffer associated with the stream passed in as an argument. 
NXFIush() is called by NXClose(), so you don’t have to flush the buffer before closing 
a stream with NXClose(). In some cases, you might not want to close the stream but 
you might want to ensure that data is actually written to the stream’s destination rather 
than remaining in the buffer. 

RETURN 

NXFlush() returns the number of characters flushed from the buffer and written to the 
stream. 

EXCEPTIONS 

This function raises an NX_illegalStream exception if the stream passed in is invalid. 
In addition, it raises an NX_illegalWrite exception if an error occurs while flushing the 
stream. 


NXFlushTypedStreamO 

SUMMARY Flush a typed stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

void NXFlushTypedStream(NXTypedStream *TypedStream) 

DESCRIPTION 

This function flushes the buffer associated with the typed stream passed in as an 
argument. NXFlushTypedStream() is called by NXCloseTypedStream(), so you 
don’t have to flush the buffer before closing a typed stream. (The NXTypedStream type 
is declared in the header file objc/typedstream.h. The structure itself is private since 
you never need to access its members.) 
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EXCEPTIONS 

NXFlushTypedStreamO raises a TYPEDSTREAM_CALLER_ERROR with the 
message “expecting a writing stream” if the typed stream wasn’t opened for writing. 

SEE ALSO 

NXOpenTypedStream() 

NXFrameRect() -> See NXDrawButton() 

NXFrameRectWithWidth() —» See NXDrawButtonQ 
NXFreeAlertPanel() —» See NXRunAlertPanel() 

NXFreeHashTable() —> See NXCreateHashTabIe() 

NXFreeObjectBufferQ —» See NXReadObjectFromBuffer() 
NXGetAlertPanel() —> See NXRunAlertPanel() 

NXGetBestDepth() -a- See NXColorSpaceFromDepthQ 
NXGetc() -> See NXPutc() 

NXGetDefaultValueO —> See NXRegisterDefaults() 

NXGetExceptionRaiser() —> See NXDefauItExceptionRaiser() 
NXGetMemoryBuffer() —> See NXOpenMemoryO 
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NXGetNamedObjectO, NXGetObjectNameO, NXNameObjectO, 
NXUnnameObjectO 


SUMMARY Refer to objects by name 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Application.h> 

id NXGetNamedObject(const char *name, id owner ) 
const char *NXGetObjectName(id theObject ) 
int NXNameObject(const char *name, id theObject, id owner ) 
int NXUnnameObject(const char *name, id owner ) 

DESCRIPTION 

These functions permit programs that use the Application Kit to refer to objects by 
name. Names are assigned with Interface Builder™ or with the NXNameObjectO 
function described here. When you create an object with Interface Builder, Interface 
Builder assigns it a default name that you can then edit or replace with a name of your 
own choosing. Underscores shouldn’t be used as part of a name. 

To distinguish among different objects with the same name, each object can also be 
assigned another object as an owner; the owner can be nil. By default. Interface Builder 
assigns the Application object (NXApp) as the owner of a Window, and a View’s 
Window as the owner of that View. 

NXGetNamedObjectO returns the id of the object having the name and owner passed 
as arguments, or nil if there is no such object. Only one object can be identified by a 
given combination of a name and owner. NXGetObjectNameO takes the id of an 
object and returns that object’s name. 

NXNameObjectO assigns an object a name and owner. An object can be assigned any 
number of different names and owners. However, if you attempt to assign a 
combination of a name and owner already used to identify another (or the same) object, 
the assignment fails. 

NXUnnameObjectO disassociates an object from the combination of a name and 
owner. Thereafter, NXGetNamedObjectO won’t return the object when passed the 
name and owner as arguments. 

RETURN 

NXGetNamedObjectO returns an object id, or nil if no object is identified by the 
combination of name and owner passed as arguments. 

NXGetObjectNameO returns the name of an object. 

NXNameObjectO returns 1 if it successfully assigns a name to an object, and 0 if not. 
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NXUnnameObjectO returns 1 if it disassociates an object from the combination of 
name and owner passed as arguments, and 0 if the name and owner weren’t associated 
with an object to begin with. 


NXGetObjectNameO —» See NXGetNamedObjectQ 


NXGetOrPeekEvent() 

SUMMARY Access event record in event queue 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Application.h> 

NXEvent *NXGetOrPeekEvent(DPSContext context, NXEvent *anEvent, int mask, 
double timeout, int threshold, int peek) 

DESCRIPTION 

NXGetOrPeekEvent() accesses an event record in an application’s event queue and 
returns a pointer to it. This function combines the facilities of DPSGetEventQ and 
DPSPeekEvent(), but unlike these client library functions, it allows your application 
to be journaled. Applications based on the Application Kit should use this function (or 
the Application class methods such as getNextEvent: and peekNextEventrinto:) to 
access event records. 

The first argument, context, represents a PostScript execution context within the 
Window Server. Virtually all applications have only one execution context, which can 
be returned using DPSGetCurrentContext(). (See the Client Library Reference 
Manual for information on DPSGetCurrentContext().) Applications having more 
than one execution context can use the constant DPS_ALLCONTEXTS to access 
events from all contexts belonging to them. The second argument, anEvent, is a pointer 
to an event record. If an event is found, its data is copied into the storage referred to by 
this pointer. 

mask determines the types of events sought. The header file dpsclient/event.h defines 
these constants for general use: 
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Constant 

NX_KEYDOWNMASK 

NX_KEYUPMASK 

NX_FLAGSCHANGEDMASK 

NX_LMOUSEDOWNMASK 

NX_LMOUSEUPMASK 

NX_RMOUSEDOWNMASK 

NX_RMOUSEUPMASK 

NX_MOUSEMOVEDMASK 

NX_LMOU SEDR AGGEDM AS K 

NX_RMOUSEDRAGGEDMASK 

NX_MOUSEENTEREDMASK 

NX_MOUSEEXITEDMASK 

NX_TIMERMASK 

NX_CURS ORUPD ATEM A S K 

NX_KITDEFINEDMASK 

NX_S Y SDEFINEDMASK 

NX_APPDEFINEDMASK 

NX_ALLEVENTS 


Event Type 

Key-down 

Key-up 

Flags-changed 

Mouse-down, left or only mouse button 
Mouse-up, left or only mouse button 
Mouse-down, right mouse button 
Mouse-up, right mouse button 
Mouse-moved 

Mouse-dragged, left or only mouse button 

Mouse-dragged, right mouse button 

Mouse-entered 

Mouse-exited 

Timer 

Cursor-update 
Kit-defined 
System-defined 
Application-defined 
All event types 


To check for multiple types of events, you can combine these constants using the 
bitwise OR operator. 


If an event matching the event mask isn’t available in the queue, 
NXGetOrPeekEvent() waits until one arrives or until timeout seconds have elapsed, 
whichever occurs first. The value of timeout can be in the range of 0.0 to 
NXJFOREVER. If timeout is 0.0, the routine returns an event only if one is waiting in 
the queue when the routine asks for it. If timeout is NX_ FOREVER, the routine waits 
until an appropriate event arrives before returning. 

threshold is an integer in the range 0 to 31 that determines which other services may be 
provided during a call to NXGetOrPeekEvent(). Requests for services are registered 
by the functions DPS AddTimedEntryO, DPSAddPort(), and DPSAddFD(). Each of 
these functions takes an argument specifying a priority level. If this level is equal to or 
greater than threshold, the service is provided before NXGetOrPeekEvent() returns. 


The last argument, peek , specifies whether NXGetOrPeekEventO removes the event 
from the event queue. If peek is 0, NXGetOrPeekEventO removes the record from the 
queue after making its data available to the application; otherwise, it leaves the record 
in the queue. 


RETURN 

If NXGetOrPeekEventO finds an event record that meets the requirements of its 
parameters, it returns a pointer to it. Otherwise, it returns NULL. 


SEE ALSO 

NXJournalMouseO, DPSGetEvent(), DPSPeekEventO, DPSDiscardEventO, 
DPS AddTimedEntryO, DPSAddPortO, DPSAddFD() 
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NXGetTempFilename() 

SUMMARY Create a temporary file name 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/appkit.h> 

char *NXGetTempFilename(char *name , int pos ) 

DESCRIPTION 

This function creates a unique file name by altering the name argument it is passed. 
NXGetTempFilenameO replaces the six characters starting at the posth position 
within name with digits it generates; it then checks whether the file name is unique. If 
it is, the file name is returned; if not, different digits are tried until a unique name is 
found. NXGetTempFilenameO is similar to the standard C function mktemp(), 
except that it can leave suffixes intact since you specify the location of the characters 
that get replaced. 

RETURN 

NXGetTempFilenameO returns a unique file name. 


NXGetTIFFInfoO -> See NXReadTIFF() 


NXGetTypedStreamZoneO, NZSetTypedStreamZone() 

SUMMARY Set zones for streams 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

NXZone *NXGetTypedStreamZone(NXTypedStream * stream ) 

void NXSetTypedStreamZone(NXTypedStream * stream, NXZone *zone) 

DESCRIPTION 

These functions let you associate a zone with a typed stream. Zones improve 
application performance by optimizing locality of reference. See the description under 
NXZoneMallocO for more on allocating and freeing zones. 
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If no zone is set for a typed stream, its zone is the default zone. Use these functions to 
associate zones with the typed streams used to unarchive objects in your application. 
You can, for example, use these functions to be sure that objects that interact are all 
unarchived in the same zone. 

Use NXSetTypedStreamZoneO to set the zone used for unarchiving objects from a 
typed stream. Use NXGetTypedStreamZone() to access the zone associated with a 
particular typed stream. 

RETURN 

NXGetTypedStreamZone() returns the zone set for stream. 
NXSetTypedStreamZoneO sets zone as the zone for stream 


NXGetUncaughtExceptionHandler() —> See 

NXSetUncaughtExceptionHandlerQ 


NXGetWindowServerMemoryO 

SUMMARY Return by reference the amount of Window Server memory being used 

by the current Window Server context 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Application.h> 

int NXGetWindowServerMemory(DPSContext context , int *vmUsedP y 
int *windowBackingP, NXStream *windowDumpStream ) 

DESCRIPTION 

NXGetWindowServerMemoryO calculates the amount of Window Server memory 
being used at the moment by the given Window Server context. If NULL is passed for 
the context, the current context is used. The amount of PostScript virtual memory used 
by the current context is returned in the int pointed to by vmUsedP ; the amount of 
window backing store used by windows owned by the current context is returned in the 
int pointed to by windowBackingP. The sum of these two numbers is the amount of the 
Window Server’s memory that this context is responsible for. 

To calculate these numbers, NXGetWindowServerMemoryO uses the PostScript 
language operators dumpwindows and vmstatus. It takes some time to execute; thus, 
calling this function in normal operation is not recommended. 
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If a non-NULL value is passed in for windowDumpStream, the information returned 
from the dumpwindows operator is echoed to the NXStream given. This can be useful 
for finding out more about which windows are using up your storage. 

RETURN 

Normally, NXGetWindowServerMemoryO returns 0. If NULL is passed for context 
and there’s no current DPS Context, returns -1. 


NXGrayComponent() —> See NXRedComponent() 
NXGreenComponentO —> See NXRedComponent() 
NXHashGetQ -» See NXHashInsert() 


NXHashlnsertO, NXHashInsertIfAbsent(), NXHashMember(), NXHashGet(), 
NXHashRemoveO, NXCountHashTable(), NXInitHashStateO, 
NXNextHashStateO 

SUMMARY Manipulate the elements of a hash table 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/hashtable.h> 

void *NXHashInsert(NXHashTable *table, const void *data ) 

void *NXHashInsertIfAbsent(NXHashTable *table, const void *data) 

int NXHashMember(NXHashTable *table, const void *data ) 

void *NXHashGet(NXHashTable *table, const void *data ) 

void *NXHashRemove(NXHashTable * table, const void *data) 

unsigned NXCountHashTable(NXHashTable * table) 

NXHashState NXInitHashState(NXHashTable *table) 

int NXNextHashState(NXHashTable *table, NXHashState *state, void **data) 
DESCRIPTION 

These functions manipulate the elements of a hash table that was created using 
NXCreateHashTable(). NXCreateHashTable(), which is described earlier in this 
chapter, returns a pointer to the NXHashTable structure it creates. You pass a pointer 
to this structure (which is defined in the header file objc/hashtable.h) for each of the 
functions described here. 
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NXHashInsert() inserts data into the hash table specified by table. It checks whether 
data is already in the table by using the function referred to by the isEqual member of 
the NXHashTablePrototype; this prototype is defined when the table is created. (See 
the description of NXCreateHashTableO for more information about defining the 
isEqual function.) If data is already in the table, the new data is inserted anyway and 
a pointer to the old data is returned. If data isn’t already in the table, it’s inserted and 
NULL is returned. 

NXHashlnsertlfAbsentO inserts data only if it isn’t already in the table and then 
returns a pointer to data. If data is already in the table, as determined using the function 
referred to by isEqual, a pointer to the existing data is returned. 

NXHashMember() checks whether data is in the hash table specified by table. If so, 
it returns a nonzero value; if not, it returns 0. NXHashGet() returns a pointer to data 
if it’s in the table; if not, it returns NULL. You can use these functions if you have a 
pointer to the data that might be stored in the table. You can also use them if data is 
stored in the table as a structure containing the key for that data and if you have that 
key. (In a hash table, the key determines where data is stored.) For example, suppose 
my hash table contains data of type My Struct and that you have a key: 

typedef struct { 

MyKey key; 

} MyStruct; 

MyStruct pseudo; 

pseudo.key = yourKey; 


You can then use your key on my hash table with either function: 


int foundlt; 

foundlt = NXHashMember(myTable, &pseudo); 


MyStruct *storedData; 

storedData = NXHashGet(myTable, Spseudo); 


NXHashRemove() removes and returns a pointer to data unless it can’t find data in the 
table, in which case it returns NULL. 

NXCountHashTable() returns the number of elements in the hash table specified by 
table. 

NXInitHashState() and NXNextHashState() iterate through the elements of a hash 
table. NXInitHashState() returns an NXHashState structure to start the iteration 
process; this structure is then passed to NXNextHashState(), which visits each 
element of the hash table and finally returns 0. (NXHashState is defined in the header 
file objc/hashtable.h; you shouldn’t use members of this structure as they may change 
in the future.) The following example counts the elements in the hash table table: 
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unsigned count = 0; 

MyData *data; 

NXHashState state = NXInitHashState(table); 

while (NXNextHashState(table, &state, &data)) 
count++; 


As it progresses through the table, NXNextHashState() reads each element of the table 
into the location specified by its third argument. 

RETURN 

NXHashInsert() returns NULL if the given data isn’t already in the table. Otherwise, 
it returns a pointer to the existing data. 

NXHashlnsertlfAbsentO returns a pointer to the given data if it isn’t already in the 
table. Otherwise, a pointer to the existing data is returned. 

NXHashMemberQ returns a nonzero value if it finds the given data in the hash table 
specified; if not, it returns 0. 

NXHashGet() returns a pointer to the given data if it’s in the table; if not, it returns 
NULL. 

NXHashRemove() returns a pointer to the data it removes unless it can’t find the data, 
in which case it returns NULL. 

NXCountHashTable() returns the number of elements in the hash table. 
NXInitHashState() returns an NXHashState for use with NXNextHashState(). 
NXNextHashState() returns 0 when it has visited every element of the hash table. 

SEE ALSO 

NXCreateHashTableQ 


NXHashlnsertlfAbsentO —» See NXHashInsert() 
NXHashMemberO —> See NXHashlnsertO 
NXHashRemoveO -» See NXHashlnsertO 
NXHighlightRectO -> See NXRectClipO 
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NXHomeDirectoryO, NXUserName() 


SUMMARY Get user’s home directory and name 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Application.h> 

const char *NXHomeDirectory(void) 
const char *NXUserName(void) 

DESCRIPTION 

These functions return the user’s home directory and name, both of which are cached 
at launch time. If the user’s id has changed since launch time or since the last time 
either of these functions was called, the values are recomputed using the standard C 
library function getpwuid(). (getpwuid() is described in its UNIX manual page.) 

RETURN 

NXHomeDirectoryO returns a pointer to the full pathname of the user’s home 
directory. NXUserNameQ returns a pointer to the user’s name. 


NXHueComponent() —> See NXRedComponent() 


NXImageBitmapO, NXReadBitmapO, NXSizeBitmapO 

SUMMARY Render and read bitmap images 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/tiff.h> 

void NXImageBitmap(const NXRect *rect , int pixelsWide, int pixelsHigh, int bps, 
int spp, int config, int mask, const void *datal, const void *data2, 
const void *data3, const void *data4, const void *data5) 

void NXReadBitmap(const NXRect *rect, int pixelsWide, int pixelsHigh, int bps, 
int spp, int config, int mask, void *datal, void *data2, void *data3, void *data4, 
void *data5) 

void NXSizeBitmap(const NXRect *rect, int *size, int * pixelsWide, int * pixelsHigh, 
int *bps, int *spp, int *config, int *mask) 
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DESCRIPTION 

The first of these functions, NXImageBitmapO, renders an image from a bitmap, 
binary data that describes the pixel values for the image. The second function, 
NXReadBitmapO, reads the bitmap for a rendered image using information about the 
image obtained from NXSizeBitmap(). NXReadBitmapO produces data that 
NXImageBitmapO can use to recreate the image. The third function, 
NXSizeBitmapO, supplies the information required by NXReadBitmapO. 

Bitmaps can also be rendered and read through the Application Kit’s 
NXBitmapImageRep class. 

NXImageBitmapO renders a bitmap image using an appropriate PostScript operator— 
image, colorimage, or alphaimage. It puts the image in the rectangular area specified 
by its first argument, rect; the rectangle is specified in the current coordinate system and 
is located in the current window. The next two arguments, pixelsWide and pixelsHigh, 
give the width and height of the image in pixels. If either of these dimensions is larger 
or smaller than the corresponding dimension of the destination rectangle, the image 
will be scaled to fit. 

The remaining arguments to NXImageBitmapO describe the bitmap data, as explained 
in the following paragraphs. 

bps is the number of bits per sample for each pixel and spp is the number of samples 
per pixel. Multiplying these two values yields the number of bits used to specify each 
pixel. 

A sample is data that describes one component of a pixel. In an RGB color system, the 
red, green, and blue components of a color are specified as separate samples, as are the 
cyan, magenta, yellow, and black components in a CMYK system. Color values in a 
gray scale are a single sample. Alpha values that determine transparency and 
opaqueness are specified as a coverage sample separate from color. 

config refers to the way data is configured in the bitmap. It should be specified as one 
of two constants: 

NX_PLANAR A separate data channel is used for each sample. The function 
provides for up to five channels, datal, data !, data3, data4, 
and data5. 

NX_MESHED Sample values are interwoven in a single channel; all values 
for one pixel are specified before values for the next pixel. 

Figure 3-2 illustrates these two ways of configuring data. 
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Figure 3-2. Planar and Meshed Configurations 


As shown in the illustration, color samples (rgb) precede the coverage sample (a) in 
both configurations. 

In the NeXTStep environment, gray-scale windows store pixel data in planar 
configuration; color windows store it in meshed configuration. NXImageBitmapO can 
render meshed data in a planar window, or planar data in a meshed window. However, 
it’s more efficient if the image has a depth (bps) and configuration ( config) that matches 
the window. 

mask specifies how the bitmap data is to be interpreted. It’s formed by joining constants 
for three kinds of information (using the bitwise OR operator): 

NX_ALPHAMASK Coverage (alpha) values are specified. If 

NX_ALPHAMASK is present in mask, spp 
should be at least 2—one more than the number 
of color components. 

NX_COLORMASK Color samples are present. If 

NX_COLORMASK isn’t included in mask, a 
gray scale is assumed. 
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NX_MONOTONICMASK In a gray scale, NX.MONOTONICMASK 

indicates that 1 equals white and 0 equals black, 
as in the PostScript model. If mask doesn’t 
include NX_MONOTONICMASK, the inverse 
scale is assumed (1 equals black, 0 equals white). 
NeXT computers use the PostScript gray scale. 

In a color system, NX_MONOTONICMASK 
indicates that CMYK (cyan, magenta, yellow, 
black) samples are specified. Its absence 
indicates RGB (red, green, blue) samples. This 
permits the function to verify that the value given 
for spp is correct. If NX_MONOTONICMASK 
is present in mask, spp should be 4 (5 if alpha 
values are also specified). If it isn’t, spp should be 
3 (4 if alpha values are also specified). 

The remaining arguments, datal through data5, specify the actual bitmap data. If 
config is NX_MESHED, only datal is read. If config is NX_PLANAR, each argument 
should specify a separate sample. 

NXReadBitmapO gets bitmap data for an existing image. It uses the PostScript 
readimage operator to read pixel values within the rectangle referred to by its first 
argument, rect. The rectangle is in the current window and is specified in the current 
coordinate system. If the rectangle is rotated so that its sides are no longer aligned with 
the screen coordinate system, NXReadBitmapO will read pixel values for the smallest 
screen-aligned rectangle enclosing the rectangle specified by rect. 

NXReadBitmapO writes the bitmap data into the buffers specified by the datal , data2, 
data3, data4, and data5 arguments. The number of actual buffers you must provide 
depends on whether there’s a separate channel for each sample ( config ) and on the 
number of samples per pixel (spp). This information, as well as other information 
about the image, should be obtained directly from the device using the 
NXSizeBitmapO function. 

When passed a pointer to a rectangle, NXSizeBitmapO gets values that 
NXReadBitmapO needs to produce a bitmap for the rectangle. It yields values that can 
be passed directly to NXReadBitmapO for the following parameters: 

pixelsWide 

pixelsHigh 

bps 

spp 

config 

mask 

It also provides the size, in bytes, that will be required for each channel of bitmap data. 
NXSizeBitmapO works through the currentwindowalpha and sizeimage operators. 
The following paragraphs describe the kinds of information you could obtain from each 
of these operators if you were to use them directly. 
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If currentwindowalpha returns 0, the image may include some transparent paint and 
you’ll need to obtain coverage values in addition to color values in the bitmap. Include 
NX_ALPHAMASK in mask, and make sure the alpha component is counted in spp. 

The sizeimage operator provides values for the pixelsWide, pixelsHigh, and bps 
parameters and for these device-dependent values: 

• The number of color samples per pixel—1 (gray scale), 3 (RGB), or 4 (CMYK). If 
there’s also an alpha component, you’ll need to add 1 to this number to obtain spp. 

• A Boolean value that reflects whether samples are meshed within a single data 
channel. If they’re not meshed, the operator returns true in a multiproc parameter, 
indicating that in the PostScript language multiple procedures would be required to 
read the various samples. 


NXInitHashState() —> See NXHashInsert() 
NXInsetRect() —> See NXSetRectO 
NXIntegralRect() -A See NXSetRectO 
NXIntersectionRect() —4 See NXUnionRect() 
NXIntersectsRectO —> See NXMouselnRectO 
NXIsAlNumO -a See NXIsAlphaQ 


NXImageBitmap() 
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NXIsAlphaO, NXIsAlNumQ, NXIsCntrl(), NXIsDigit(), NXIsGraph(), 
NXIsLower(), NXIsPrintO, NXIsPunct(), NXIsSpaceO, NXIsUpper(), 
NXIsXDigitQ, NXIsAsciiQ 


SUMMARY Classify NeXTstep-encoded values 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <NXCType.h> 

int NXIsAlpha(unsigned c) 
int NXIsAlNum(unsigned c ) 
int NXIsUpper(unsigned c ) 
int NXIsLower(unsigned c) 
int NXIsDigit(unsigned c ) 
int NXIsXDigit(unsigned c ) 
int NXIsSpace(unsigned c) 
int NXIsPunct(unsigned c ) 
int NXIsPrint(unsigned c) 
int NXIsGraph (unsigned c) 
int NXIsCntrl(unsigned c) 
int NXIsAscii(unsigned c) 


DESCRIPTION 

These functions classify NeXTstep-encoded integer values. They return a nonzero 
value if the tested value belongs to the indicated class of characters or 0 if it does not. 

These functions are similar to the standard C library routines for testing ASCII- 
encoded integer values (see the UNIX manual page for ctype), except that they act on 
the extended character set defined by NeXTStep encoding. For example, both isalpha() 
and NXIsAlphaO classify the character “a” as a letter; however, only NXIsAlphaO 
classifies “a” as a letter. The functions make these tests: 


Function 


Tests that c is; 


NXIsAlpha(c) 

NXIsUpper(c) 

NXIsLower(c) 

NXIsDigit(c) 

NXIsXDigit(c) 

NXIsAlNum(c) 

NXIsSpace(c) 

NXIsPunct(c) 

NXIsPrint(c) 

NXIsGraph(c) 

NXIsCntrl(c) 

NXIsAscii(c) 


a letter 

an uppercase letter 
a lowercase letter 
a digit 

a hexadecimal digit 
an alphanumeric character 

a space, tab, carriage return, newline, vertical tab, or formfeed 
a punctuation character (neither control nor alphanumeric) 
a printing character 

a printing character; like NXIsPrint() except false for space 
a control character (0x00 through Ox IF, 0x7F, 0x80, OxFE, OxFF) 
an ASCII character (code less than 0x7F) 
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RETURN 

Each of these functions returns a nonzero value if the tested value belongs to the 
indicated class of characters or 0 if it does not. 

SEE ALSO 
NXToAscii() 

NXIsAsciiO -> See NXIsAlpha() 

NXIsCntrlO See NXIsAlpha() 

NXIsDigitO -> See NXIsAlpha() 

NXIsGraph() -> See NXIsAlpha() 

NXIsLowerO -a See NXIsAlpha() 

NXIsPrintO -> See NXIsAlpha() 

NXIsPunct() -> See NXIsAlpha() 

NXIsServicesMenuItemEnabled() —> See NXSetServicesMenuItemEnabled() 
NXIsSpaceO See NXIsAlpha() 

NXIsUpperQ -a See NXIsAlpha() 

NXIsXDigitQ -> See NXIsAlphaQ 
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NXJournalMouseO 


SUMMARY Allow journaling during direct mouse tracking 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/NXJournaler.h> 
void NXJournalMouse(void) 

DESCRIPTION 

This function lets an application that accesses the status of the mouse directly (by 
calling functions such as PSstiIIdown() or PScurrentmouse()) participate in event 
journaling. If your application tests the status of the mouse by analyzing event records 
received through the Application Kit’s normal distribution mechanism, you won’t need 
to call this function. 

For an application to be journaled, it must ask for events. If a routine in your 
application bypasses the Kit’s event distribution system to test the mouse’s position or 
button status, it must call NXJournalMouseO to ensure that its activities can be 
journaled. For example, a routine that takes some action as long as the mouse button 
is depressed should call NXJournalMouseO before testing the mouse: 

do { 

NXJournalMouse(); 

PSstilldown(mouseDownEvent.data.mouse.eventNum, SstillDown); 

/* Do some action */ 

} while (stillDown); 

NXJournalMouseO asks for a journal-event, mouse-up, or mouse-dragged event, 
sends a copy to the joumaler (if one is recording), and then discards the event. 

Note: In the example above, releasing the mouse button causes the loop to exit. If the 
loop didn’t call NXJournalMouseO, the mouse-up event would remain in the event 
queue after the loop exited. With the addition of NXJournalMouseO, this event is 
discarded. For most applications, this difference is of no consequence. 

SEE ALSO 

NXGetOrPeekEventO 
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NXLogError() 

SUMMARY Write a formatted error string 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/nextstd.h> 

void NXLogError(const char * format ,...) 

DESCRIPTION 

NXLogError() is much like printf(). It writes a formatted string to the Console or 
stderr, depending on whether the application was launched from the Workspace 
Manager or some shell. NXLogError() calls syslogO, which marks the message with 
the time of occurrence and the application’s process identification number. See the 
UNIX manual page for syslogO for more information. 

SEE ALSO 

NX_RAISE(), NXDefaultExceptionRaiser(), NXRegisterErrorReporter() 


NXMagentaComponent() —> See NXRedComponent() 
NXMallocCheck() -> See NXZoneMalloc() 
NXMapFileO —> See NXOpenMemory () 
NXMergeZone()—> See NXZoneMallocO 
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NXMouselnRectO, NXPointlnRectO? NXIntersectsRectO? NXContainsRectO? 
NXEqualRectQ, NXEmptyRectQ 


SUMMARY Test graphic relationships 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

BOOL NXMouseInRect(const NXPoint *aPoint, const NXRect *aRect, 

BOOL flipped) 

BOOL NXPointInRect(const NXPoint *aPoint, const NXRect *aRect) 

BOOL NXIntersectsRect(const NXRect *aRect, const NXRect *bRect) 

BOOL NXContainsRect(NXRect *aRect, const NXRect *bRect) 

BOOL NXEqualRect(const NXRect *aRect, const NXRect *bRect) 

BOOL NXEmptyRect(const NXRect *aRect ) 

DESCRIPTION 

These functions test the rectangles referred to by their arguments; they return YES if 
the test succeeds and NO if it fails. The functions that take two arguments assume that 
both arguments are expressed in the same coordinate system. 

NXMouselnRectO is used to determine whether the hot spot of the cursor is inside a 
given rectangle. It returns YES if the point referred to by its first argument is located 
within the rectangle referred to by its second argument. If not, it returns NO. It 
assumes an unsealed and unrotated coordinate system. 

The hot spot is the point within the cursor image that’s used to report the cursor’s 
location. It’s situated at the upper left comer of a critical pixel in the cursor image, the 
one cursor pixel that’s constrained to always be on screen. NXMouselnRectO is 
designed to return YES when this pixel is inside the rectangle, and NO when it’s not. 
Thus if the point referred to by aPoint lies along the upper or left edge of the rectangle, 
this function should return YES. But if the point lies along the lower or right edge of 
the rectangle, it should return NO. To make this determination, the function needs to 
know the polarity of the y-axis. The third argument, flipped, should be NO if the 
positive y-axis extends upward, and YES if the coordinate system has been flipped so 
that the positive y-axis extends downward. (For convenience, View’s mouse:inRect: 
method automatically determines whether the coordinate system is flipped. See the 
View class specification in Chapter 2 for more information about this method.) 

NXPointlnRectO performs the same test as NXMouselnRectO but assumes a flipped 
coordinate system. If the coordinate system is unflipped, it gives the wrong result if the 
point is coincident with the maximum or minimum y-coordinate of the rectangle. You 
should use NXMouselnRectO when testing the cursor’s location. 

NXContainsRectO returns YES if aRect completely encloses bRect. Otherwise, it 
returns NO. 
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NXIntersectsRect() returns YES if the two rectangles overlap, and NO otherwise. 
Adjacent rectangles that share only a side are not considered to overlap. 

It’s possible for NXIntersectsRectO to return NO even though the two rectangles 
include some of the same pixels. This can happen when the rectangles don’t have any 
area in common, yet their outlines pass through some of the same pixels—for example, 
when they share a side not at a pixel boundary. In the NeXT imaging model, any pixel 
an outline passes through is treated as if it were inside the outline. 

NXEqualRectO returns YES if the two rectangles are identical, and NO otherwise. 

NXEmptyRectO returns YES if the rectangle encloses no area at all—that is, if it has 
no height or no width (or if its width or height is negative). If the height and width are 
both positive, it returns NO. 

RETURN 

These functions all return YES to indicate that the test succeeded and NO to indicate 
that it did not. 

SEE ALSO 

NXUnionRectO, NXSetRectQ 


NXNameObject() —> See NXGetNamedObject() 

NXNameZoneO —> See NXZoneMalIoc() 

NXNextHashState() —> See NXHashInsert() 

NXNoEffectFree() -A See NXCreateHashTable() 
NXNumberOfColorComponentsO —> See NXColorSpaceFromDepth() 
NXOffsetRectO -> See NXSetRectQ 
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NXOpenFileQ, NXOpenPortQ 


SUMMARY Open a file stream or a Mach port stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

NXStream *NXOpenFile(int/<i, int mode) 

NXStream *NXOpenPort(port_t port, int mode ) 

DESCRIPTION 

These functions connect a stream to a file or a Mach port. (The NXStream structure is 
defined in the header file streams/streams.h.) 

NXOpenFile() opens a stream on the file specified by the file descriptor argument ,fd, 
which can refer to a pipe or a socket. (If the file is stored on disk, use NXMapFileO; 
this function is described below under NXOpenMemoryO.) The mode argument 
should be one of the three constants NX_READONLY, NX_WRITEONLY, or 
NX_READWRITE to specify how the stream will be used. The mode should be the 
same as the one used when obtaining the file descriptor. (The system call open(), which 
returns a file descriptor, takes 0_RDONLY, 0_WRONLY, or 0_RDWR to indicate 
whether the file will be used for reading, writing, or both. For more information on this 
function, see its UNIX manual page.) 

You can use NXOpenFile() to connect to stdin, stdout, and stderr by obtaining their 
file descriptors using the standard C library function fileno(). (For more information 
on this function, see its UNIX manual page.) 

NXOpenPortO opens a stream associated with the Mach port specified by port. The 
mode must be either NX_READONLY or NX_WRITEONLY. The port must already 
be allocated using the Mach function port_allocate(). See the “Mach Functions” 
section later in this chapter for more information about using this function. 

Once the file or Mach port stream is open, you can read from or write to it. See the 
descriptions of NXReadO and NXPutc() for more information about the functions 
available for reading or writing to a stream. 

When you’re finished with the stream, close it with NXCIose(). If you’ve written to the 
stream, the data will be automatically saved in the file. After calling NXCIose() on a 
file stream, you still need to close the file descriptor. To d© this, use the system call 
close(), giving it the file descriptor as an argument. (For more information about 
close(), see its UNIX manual page.) 
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RETURN 

Both functions return a pointer to the stream they open or NULL if an error occurred 
while trying to open the stream. 

SEE ALSO 

NXOpenMemory(), NXReadQ, NXPutcQ, NXCloseQ 


NXOpenMemoryO, NXMapFileO, NXSaveToFile(), NXGetMemoryBuffer(), 
NXCloseMemoryO 

SUMMARY Manipulate a memory stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

NXStream *NXOpenMemory(const char * address, int size, int mode) 

NXStream *NXMapFile(const char *pathName, int mode) 
int NXSaveToFile(NXStream * stream, const char *name) 
void NXGetMemoryBuffer(NXStream * stream, char **streambuf, int *len, 
int *maxleri) 

void NXCIoseMemory(NXStream * stream, int option) 

DESCRIPTION 

These functions open, save, and close streams on memory. (The NXStream structure 
is defined in the header file streams/streams.h.) 

NXOpenMemoryO returns a pointer to the memory stream it opens. Its argument 
mode specifies whether the stream will be used for reading or writing. If 
NX_WRITEONLY is specified, the first two arguments should be NULL and 0 to allow 
the amount of memory available to be automatically adjusted as more data is written. 
Any other value for address should be the starting address of memory allocated with 
vm_allocate(). If NX_READONLY is specified, a memory stream will be set up for 
reading the data beginning at the location specified by the first argument; the second 
argument indicates how much data will be read. To use the stream for both writing and 
reading, you can either use NULL and 0 or specify the location and amount of data to 
be read; again, address should be the starting address of memory allocated with 
vm_allocate(). 

NXMapFile() maps a file into memory and then opens a memory stream. A related 
function, NXOpenFileO, connects a stream to a file specified with a file descriptor. 
(This function is described earlier in this chapter.) Memory mapping allows efficient 
random and multiple access to the data in the file, so NXMapFileO should be used 
whenever the file is stored on disk. When you call NXMapFileO, give it the pathname 
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for the file and indicate whether you will be writing, reading, or both, by using one of 
the mode constants described above. If you use the stream only for reading, just close 
the memory stream when you’re finished. If you write to the memory-mapped stream, 
you need to call NXSaveToFile(), as described below, to save the data. 

Once the memory stream is open, you can read from or write to it. See the descriptions 
of NXRead() and NXPutc() for more information about reading or writing to a stream. 

Before you close a memory stream, you can save data written to the stream in a file. To 
do this, call NXSaveToFile(), giving it the stream and a pathname as arguments. 
NXSaveToFileO writes the contents of the memory stream into the file, creating it if 
necessary. After saving the data, close the stream using NXCloseMemory(). 

NXGetMemoryBufferO returns the memory buffer ( streambuf) and its current and 
maximum lengths (len and maxlen). 

When you’re finished with a memory stream, close it by calling NXCloseMemory(). 
Typically, NX_FREEBUFFER will be used as the second argument to free all memory 
used by the stream, but there are two other constants available. If you’ve used the 
stream for writing, more memory may have been made available than was actually 
used; the constant NX_TRUNCATEBUFFER indicates that any unused pages of 
memory should be freed. (Calling NXClose() with a memory stream is equivalent to 
calling NXCIoseMemoryO and specifying NX_TRUNCATEBUFFER.) 
NX_SAVEBUFFER doesn’t free the memory that had been made available. 

RETURN 

NXOpenMemoryO and NXMapFile() return a pointer to the stream they open or 
NULL if the stream couldn’t be opened. 

NXSaveToFileO returns -1 if an error occurred while opening or writing to the file and 
0 otherwise. 

EXCEPTIONS 

The functions in this group that take a stream as an argument raise an NX_illegalStream 
exception if the stream is invalid. This exception is also raised if these functions are 
used on a stream that isn’t a memory stream. 

SEE ALSO 

NXReadO, NXPutc(), NXOpenFileO 


NXOpenPort() —> See NXOpenFileO 
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NXOpenTypedStream(), NXCloseTypedStream(), 
NXOpenTypedStreamForFileQ 


SUMMARY Open or close a typed stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

NXTypedStream *NXOpenTypedStream(NXStream * stream, int mode) 
void NXCloseTypedStream(NXTypedStream *typedStream) 

NXTypedStream *NXOpenTypedStreamForFile(const char *fileName, int mode) 

DESCRIPTION 

These functions open, save the contents of, and close a typed stream. A typed stream 
should be used for archiving—that is, for saving Objective-C objects for later use, 
typically in a file. (The NXTypedStream type is declared in the header file 
objc/typedstream.h. The structure itself is private since you never need to access its 
members.) 

The first argument for NXOpenTypedStream() is an already opened NXStream 
structure. See the descriptions of NXOpenMemoryO, NXOpenFile(), and 
NXOpenPortO earlier in this chapter for more information about opening a stream. 
The second argument to NXOpenTypedStream() must be NX_READONLY or 
NX_WRITEONLY to specify how the typed stream will be used. 

Once the typed stream is open, you can write to or read from it. See the descriptions of 
NXReadType(), NXReadObjectO, and NXReadPointO later in this chapter for more 
information about reading and writing. When you’re finished with the typed stream, 
you must first close the typed stream using NXCloseTypedStream() and then close the 
NXStream structure. See the descriptions of NXClose() and NXCloseMemoryO for 
more information about closing a stream. 

To open a typed stream on a file, use NXOpenTypedStreamForFile(). This function 
opens a memory stream and an associated typed stream. If mode is NX_READONLY, 
the typed stream is initialized with the contents of the file specified by fileName. A 
subsequent call to NXCloseTypedStream() will close the NXTypedStream and 
NXStream structures and free the buffer that had been used. If mode is 
NX_WRITEONLY, a typed stream on memory is opened, ready for writing. When you 
finish writing, calling NXCloseTypedStream() will flush the typed stream, save its 
contents in the file specified by fileName, close both the NXTypedStream and the 
NXStream structures, and free the buffer used. 

RETURN 

NXOpenTypedStream() and NXOpenTypedStreamForFile() return a pointer to the 
typed stream they open or NULL if the stream couldn’t be opened. 
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EXCEPTIONS 


NXOpenTypedStream() and NXOpenTypedStreamForFile() raise a 
TYPEDSTREAM_CALLER_ERROR exception with the message 
“NXOpenTypedStream: invalid mode” if the mode is anything other than 
NX_READONLY or NX_WRITEONLY. 

NXOpenTypedStream() raises a TYPEDSTREAM_CALLER_ERROR exception 
with the message “NXOpenTypedStream: null stream” if an invalid NXStream 
structure is passed in. 

SEE ALSO 

NXOpenMemoryO, NXOpenFileO, NXCIose(), NXCloseMemoryO, 
NXReadTypeO, NXReadObjectQ, NXReadPoint() 


NXOpenTypedStreamForFileO -a See NXOpenTypedStream() 


NXOrderStrings(), NXDefaultStringOrderTable() 

SUMMARY Provide table-driven string ordering service 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Text.h> 

int NXOrderStrings(const unsigned char *sl, const unsigned char *s2, 

BOOL caseSensitive, int length , NXStringOrderTable *table) 
NXStringOrderTable *NXDefaultStringOrderTable(void) 

DESCRIPTION 

NXOrderStrings() returns a value indicating the ordering of the strings si and s2, as 
determined by the NXStringOrderTable structure table. If caseSensitive is NO, capital 
and lowercase versions of a letter are considered to have identical rank. The 
comparison considers at most the first length characters of each string. For 
convenience, you can pass -1 for length if both strings are null-terminated. If table is 
NULL, the default ordering table (as described below) is used. NXOrderStrings() 
returns 1, 0, or -1 depending on whether si is greater than, equal to, or less than s2 
according to table. 

When comparing strings that are visible to the user, you should generally use 
NXOrderStringsCsT, s2, YES, -1, NULL) as a replacement for strcmp(s7, s2) and 
NXOrderStrings(si, s2, YES, n, NULL) as a replacement for strncmp(si, s2 , n). 
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NXOrderStringsO consults an NXStringOrderTable structure when comparing 
strings. This structure is declared in appkit/Text.h: 


typedef struct { 

unsigned char primary[256]; 
unsigned char secondary[256]; 
unsigned char primaryCI[256]/ 
unsigned char secondaryCI[256]; 
} NXStringOrderTable; 


The first two arrays contain ordering information for case sensitive searches; the last 
two are for case insensitive searches. NXOrderStringsO determines a character’s rank 
by using the character to index into the appropriate primary array. The value found at 
that position determines the character’s rank. For example, in the default ordering table 
the value at the ‘a’ position is less than that at the ‘b’ position, but the values at the ‘o’ 
and ‘o’ positions are identical. The secondary arrays provide additional ordering 
information for ligature characters (such as ‘as’ and ‘fl’), in effect breaking the ligature 
apart for the purposes of ordering. Thus, the two characters ‘ae’ and the single 
character ‘ae’ are given equal rank. 

NeXTStep provides a default order table, which can by accessed by calling 
NXDefaultStringOrderTable(). If you want to create your own order table, it’s best 
to start with the default table and algorithmically modify it (perhaps in conjunction with 
the NXCType routines—see /usr/include/NXCTypes.h). In this way, you’ll benefit 
from using character tables that have already been localized. The entry at the 0 position 
in each array must be 0. 


RETURN 

NXOrderStringsO returns 1, 0, or -1 depending on whether si is greater than, equal 
to, or less than s2 according to table. NXDefaultStringOrderTable() returns a pointer 
to the default string order table. 


NXOrderStrings() 
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NXPingO 


SUMMARY Synchronize the application with the Window Server 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXPing(void) 

DESCRIPTION 

NXPingO helps applications synchronize their actions with the actions of the Window 
Server; it enables an application to respond smoothly to user events. 

An application can generate PostScript code faster than the Window Server can 
interpret it. An application can therefore “get ahead” of the Server—it can get events 
and respond to them before its responses to previous events are displayed to the user. 
To the user, it appears that the application is slow, or that there’s discontinuity between 
an event and the response. 

NXPingO causes the application to pause until the Window Server catches up. It 
flushes the connection buffer so that all current PostScript code is sent to the Server and 
returns only when all the code has been interpreted. It’s a cover for the 
DPSWaitContextO function when passed the context returned by 
DPSGetCurrentContext(): 


DPSWaitContext(DPSGetCurrentContext()) 

For more information on these two Display PostScript functions, see the Client Library 

Reference Manual. 

Waiting for the Window Server to catch up with the application is sometimes a good 

idea, for two reasons: 

• It lets the Server have full access to the CPU. The application stops competing with 
it for system resources. 

• It gives the application a chance to generate less, and more relevant, PostScript 
code. An application won’t fall even further behind the user while it waits for the 
Window Server if it combines its responses to events or allows events to be 
coalesced in the event queue. 
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NXPingO is most typically used in a modal loop. In a tracking loop, it should be called 
just before getting each new event (after all the PostScript code has been generated in 
response to the last event). The following schematic for a mouseDown: method 
illustrates its use. (Comments that would be replaced by code in any real method are 
shown in italic type.) 


- mouseDown:(NXEvent *)thisEvent 
{ 

BOOL shouldLoop = YES; 

int oldMask = [window addToEventMask:NX_LMOUSEDRAGGEDMASK]; 

while ( shouldLoop ) { 

/* 

* Draw in response to the event 
*/ 

NXPing () ; 

theEvent = [NXApp getNextEvent:(NX_LMOUSEUPMASK 

| NX_LMOUSEDRAGGEDMASK)]; 
if ( theEvent->type == NX_LMOUSEUP ) 
shouldLoop = NO; 

} 

/* 

* Replace dynamic drawing with a static display 
*/ 

[window setEventMask:oldMask]; 
return self; 

} 

During the wait imposed by NXPingO, mouse-dragged (and mouse-moved) events will 
be coalesced in the event queue. When the application next gets an event, it will be a 
more up-to-date one than if NXPingO had not been used. Coalescing also serves to 
reduce the total amount of PostScript code generated. 

NXPingO also lets an application more efficiently group its responses to a number of 
similar events. In the following example, the method that responds to key-down events 
uses the peekNextEvent:into: method to take all available key-down events from the 
event queue and display them at once. The use of NXPingO means that the example 
will be invoked less often than it otherwise would. However, it will consolidate events 
into fewer instructions for the Window Server. 


NXPingO 
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- keyDown:(NXEvent *)theEvent 

{ 

/* 

* Check theEvent->data. key. charSet and 

* theEvent->data.key.charCode and set up the array of 

* characters to displayed 
*/ 

while ( 1 ) { 

/* Peek at the next event */ 

NXEvent next; 

theEvent = [NXApp peekNextEvent:NX_ALLEVENTS into:&next]; 

/* Break the loop if there is no next event */ 
if ( !theEvent ) 
break; 

/* Skip over key-up events */ 

else if ( theEvent->type == NX_KEYUP ) { 

[NXApp getNextEvent :NX__KEYUPMASK] ; 
continue; 

} 

/* Respond only to key-down events */ 
else if ( theEvent->type == NX_KEYDOWN ) { 

/* 

* Add the new character to the array to be displayed 

*7 

[NXApp getNextEvent:NX_KEYDOWNMASK]; 

} 

/* Break the loop on all other events types */ 
else 

break; 

} 

/* 

* Display the array of characters 
*/ 

NXPing () ; 
return self; 

} 

The wait imposed by NXPingO may mean that there are more key-down events in the 
event queue each time this method is invoked. Since it’s much more efficient for the 
application to send fewer instructions to the Window Server to display longer strings, 
this delay helps rather than hurts. 

In the examples shown above, NXPingO is called just before the application is ready 
to get another event. This is the most appropriate place for it, since it means that the 
response to the last event will be complete—including the Window Server’s part— 
before the response to the next event begins. It might be noted that both NXPingO and 
the functions and methods that get events flush the output buffer to the Window Server. 
However, the buffer isn’t flushed if it’s empty, so calling NXPingO before getting an 
event doesn’t cause an extra operation to be performed. 
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Using NXPingO has two negative consequences: 

• It reduces the Window Server’s throughput—the amount of PostScript code that it 
can interpret in a given time period. This is mainly due to the increased 
communication between the Server and the application. 

• It reduces the granularity of the application’s response to events. When events are 
coalesced in the event queue, cursor movements are tracked at greater intervals. 

Therefore, you should not use NXPingO in a simple event loop unless the time needed 
to execute the PostScript code each event generates is longer than the time needed to 
complete the loop. 

Although NXPingO is most often used in modal loops, it’s also appropriate to use it in 
situations where information from the Window Server is needed before the application 
can proceed. For example, you may want to call NXPingO before entering a section of 
code that depends on previous PostScript instructions being executed without error. 
Since your application won’t get notified of any errors until the PostScript code is. 
actually executed, NXPingO allows it to wait for the notification before proceeding. 

SEE ALSO 

DPSFlush() 


NXPointlnRectO —> See NXMouselnRectO 


NXPortFromNameO, NXPortNameLookupO 

SUMMARY Get send rights to an application port 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/ Listener.h> 

port_t NXPortFromName(const char *name, const char *host) 
port_t NXPortNameLookup(const char *name, const char *host) 

DESCRIPTION 

NXPortFromNameO and NXPortNameLookupO both return send rights to the port 
that’s registered with the Network Name Server under name for the host machine. If 
host is a NULL pointer or an empty string, the local host is assumed. This is the most 
common usage. 
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An application generally registers with the Network Name Server under the name it 

TM • 

uses for its executable file. For example, Digital Webster registers under “Webster” 
and Mail under “Mail”. 

If no port is registered for the name application, NXPortNameLookupO returns 
PORT_NULL. However, NXPortFromNameO tries to have host’s Workspace 
Manager launch the application. If the application can be launched and if it registers 
with the Network Name Server, send rights to its port are returned. This strategy is 
almost always successful for the local host. It’s more problematic for a remote host, 
since the Workspace Manager is normally protected from messages coming from other 
machines. 

If, in the end, no port can be found for the name application, NXPortFromNameO, like 
NXPortNameLookupO, returns PORT_NULL. 

Applications should use these two functions, rather than the Mach netname_look_up() 
function, to get send rights to a public port. Although both functions currently use 
netname_look_up() to find the port, this may not always be true. In future releases, 
Listener objects may “check in” with another service—such as the Bootstrap Server— 
rather than the Network Name Server. In this case, the two functions described here 
will continue to find and return the port associated with name, but netname_look_up() 
will not. 

RETURN 

Both functions return send rights to the public port of the name application on the host 
machine, or PORTJNfULL if the port can’t be found. 


NXPortNameLookupO -a See NXPortFromNameO 
NXPrintfO —> See NXPutc() 

NXPtrHashO -> See NXCreateHashTabIe() 
NXPtrlsEqualO —> See NXCreateHashTable() 
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NXPutcO, NXGetcO, NXUngetc(), NXScanf(), NXPrintf(), NXVScanf(), 
NXVPrintfO 

SUMMARY Read or write formatted data to or from a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

int NXPutc(NXStream * stream, char c) 

int NXGetc(NXStream * stream) 

void NXUngetc(NXStream * stream) 

int NXScanf(NXStream * stream, const char * format ,...) 

void NXPrintf(NXStream * stream, const char * format ,...) 

int NXVScanf(NXStream * stream, const char * format, va_list argList) 

void NXVPrintf(NXStream * stream , const char * format, va_list argList) 

DESCRIPTION 

These functions and macros read and write data to and from a stream that has already 
been opened. (See the descriptions of NXOpenMemoryO and NXOpenFile() for 
more information about opening a stream.) After writing to a stream, you may need to 
call NXFlush() to flush data from the buffer associated with the stream. (See the 
description of NXFlushQ earlier in this chapter.) 

The macros for writing and reading single characters at a time are similar to the 
corresponding standard C functions: NXPutc() and NXGetcO work like putc() and 
getc(). NXPutcO appends a character to the stream. Its second argument specifies the 
character to be written to the stream. NXGetcO retrieves the next character from the 
stream. To reread a character, call NXUngetc(). This function puts the last character 
read back onto the stream. NXUngetc() doesn’t take a character as an argument as 
ungetc() does. NXUngetc() can only be called once between any two calls to 
NXGetcO (or any other reading function). 

The other four functions convert strings of data as they’re written to or read from a 
stream. NXPrintf() and NXScanf() take a character string that specifies the format of 
the data to be written or read as an argument. NXPrintf() interprets its variables 
according to the format string and writes them to the stream. Similarly, NXScanf() 
reads characters from the stream, interprets them as specified in the format string, and 
stores them in the variables indicated by the last set of arguments. The conversion 
characters in the format string for both functions are the same as those used for the 
standard C library functions, printf() and scanfQ. For detailed information on these 
characters and how conversions are performed, see the UNIX manual pages for printf() 
and scanf(). 
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Two related functions, NXVPrintf () and NXVSeanf(), are exactly the same as 
NXPrintf() and NXScanfQ, except that instead of being called with a variable number 
of arguments, they are called with a va_list argument list, which is defined in the header 
file stdarg.h. This header file also defines a set of macros for advancing through a 
valist. 

RETURN 

NXPutc() and NXGetcQ return the character written or read. NXScanf() and 
NXVScanf() return EOF if all data was successfully read; otherwise, they return the 
number of successfully read data items. 

SEE ALSO 

NXOpenMemory(), NXOpenFileQ, NXFlushQ, NXReadQ 
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NXReadO, NXWriteQ 


SUMMARY Read from or write to a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

int NXRead(NXStream * stream , void *buf, int count ) 
int NXWrite(NXStream * stream, const void *buf, int count) 

DESCRIPTION 

These functions read and write multiple bytes of data to a stream that has already been 
opened. (See the descriptions of NXOpenMemoryO and NXOpenFile() for more 
information about opening a stream.) After writing to a stream, you may need to call 
NXFIush() to flush data from the buffer associated with the stream. (See the 
description of NXFlush() earlier in this chapter.) 

These functions write multiple bytes of data to and read them from a stream. To read 
data from a stream, call NXReadQ: 

NXRect myRect; 

NXRead(stream, SmyRect, sizeof(NXRect)); 


NXReadO reads the number of bytes specified by its third argument from the given 
stream and places the data in the location specified by the second argument. 

In the following example, an NXRect structure is written to a stream. 


NXRect myRect; 

NXSetRect(SmyRect, 0.0, 0.0, 100.0, 200.0); 

NXWrite(stream, SmyRect, sizeof(NXRect)); 

The second and third arguments for NXWrite() give the location and amount of data 
(measured in bytes) to be written to the stream. 

RETURN 

These functions return the number of bytes written or read. If an error occurs while 
writing or reading, not all the data will be written or read. 

SEE ALSO 

NXFhishQ 


NXReadO 
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NXReadArrayO, NXWriteArrayO 


SUMMARY Read or write arrays from or to a typed stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

void NXReadArray(NXTypedStream *typedStream, const char *dataType, int count, 
const void *data) 

void NXWriteArray(NXTypedStream *typedStream, const char *dataType, int count, 
void *data) 

DESCRIPTION 

These functions read and write arrays from and to a typed stream. They can be used 
within read: or write: methods for archiving purposes. See the description of 
NXReadObjectO in this chapter for more about these methods. Functions are also 
available for reading and writing other data types; they’re listed below under “SEE 
ALSO.” 

Before using a typed stream for reading and writing, it must be opened; see the 
description of NXOpenTypedStreamQ for details on opening a typed stream. (The 
NXTypedStream type is declared in the header file objc/typedstream.h. The structure 
itself is private since you never need to access its members.) 

NXReadArrayO and NXWriteArrayO read and write an array of count elements of 
type dataType from or to typedStream. NXReadArrayO reads the array from the typed 
stream into the location specified by data, which must have been previously allocated. 
NXWriteArrayO writes the array specified by data to the typed stream. Both 
functions use the characters listed under the description of NXReadType() for 
dataType. 

The following is an example of an integer array being written. To read the same array, 
NXReadArrayO would be called with the same first three arguments as 
NXWriteArrayO; the fourth argument would be a pointer to memory for the array. 

int aa[4]; 

aa[0] = 0; aa[l] = 11; aa[2] = 22; aa[3] = 33; 

NXWriteArray(typedStream, "i", 4, aa); 


EXCEPTIONS 

Both functions check whether the typed stream has been opened for reading or for 
writing and raise a TYPEDSTREAM_FILE_INCONSISTENCY exception if it isn’t 
correct. For example, if NXReadArrayO is called and the stream was opened for 
writing, the exception is raised. 
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NXReadArrayO raises a TYPEDSTREAM_FILE_INCONSISTENCY exception if 
the data to be read is not of the expected type. 

SEE ALSO 

NXOpenTypedStream(), NXReadTypeQ, NXReadObjectQ, and NXReadPoint() 


NXReadBitmapO —> See NXImageBitmapO 


NXReadColorO, NXWriteColor() 

SUMMARY Read and write a color from a typed stream 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

NXColor NXReadColor(NXTypedStream * stream) 

void NXWriteColor(NXTypedStream * stream, NXColor color ) 

DESCRIPTION 

NXReadColorO reads a color from the typed stream, stream , and returns it. 
NXWriteColorO writes a color value, color, to a typed stream. The stream can be 
connected to a file, to memory, or to some other repository for data. 

NXColor values should be read and written only using these functions. When a color 
is written by NXWriteColorO and then read back by NXReadColorO, the color is 
guaranteed to be the same. This cannot be guaranteed if NXColor structures are read 
and written directly—for example, through standard C functions like fread() and 
fwrite(). The internal format of an NXColor data structure is not specified and 
therefore may change in future releases. 

RETURN 

NXReadColorO returns the color value it reads. 

EXCEPTION 

NXReadColorO raises an NX_newerTypedStream exception if the data it’s expected 
to read is not of type NXColor. 

SEE ALSO 

NXSetColorO, NXConvertRGBAToColorO, NXConvertColorToRGBA(), 
NXEqualColor(), NXRedComponentO, NXChangeRedComponentO 
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NXReadDefauItO -> See NXRegisterDefaults() 


NXReadObjectO, NXWriteObject(), NXWriteObjectReference(), 
NXWriteRootObjectO 

SUMMARY Read or write Objective-C objects from or to a typed stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

id NXReadObject(NXTypedStream *typedStream ) 

void NXWriteObject(NXTypedStream ^typedStream, id object ) 

void NXWriteObjectReference(NXTypedStream *typedStream, id object) 

void NXWriteRootObject(NXTypedStream ^typedStream, id rootObject) 

DESCRIPTION 

These functions initiate the archiving and unarchiving processes for Objective-C 
objects. They read and write the object passed in from or to typedStream. When an 
object is archived with these functions, its class is automatically written as well. In 
addition, the data type of each of its instance variables is archived along with the value 
of the variable. These functions also ensure that objects are written only once. 

Before you use a typed stream for reading and writing, it must be opened; see the 
description of NXOpenTypedStream() for details on opening a typed stream. (The 
NXTypedStream type is declared in the header file objc/typedstream.h. The structure 
itself is private since you never need to access its members.) 

NXReadObjectO begins the unarchival process by allocating memory for a new object 
of the correct class. It then sends the object a read: message to initialize its instance 
variables from the typed stream, read: messages should only be generated through 
NXReadObjectO; they shouldn’t be sent directly to objects. Application Kit objects 
already have read: methods, but you need to implement read: methods for any classes 
you create that add instance variables: 

- read: (NXTypedStream *)typedStream 
{ 

[super read:typedStream]/ 

. . ./* code for reading instance variables declared in 


The message to super ensures that inherited instance variables will be unarchived. The 
body of the read: method unarchives the object’s instance variables, using the 
appropriate function for that data type. The functions available for unarchiving include 
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NXReadTypes(), NXReadPointQ, and NXReadArray (), as well as 
NXReadObject(). See the descriptions of these functions in this chapter for 
information about how to use them. A read: method can also check the version of the 
class being unarchived. See the description of NXTypedStreamClassVersion() for 
more information about how to do this. 

After NXReadObject() unarchives an object, it sends the object awake and 
finishUnarchiving messages. You can implement an awake method to initialize the 
object to a usable state. The finishUnarchiving method allows you to replace the 
just-unarchived object with another one. If you implement a finishUnarchiving 
method, it should free the unarchived object and return the replacement object. 

NXWriteObject() writes object to typedStream by sending the object a write: 
message. As is the case with read: methods, write: methods shouldn’t be sent directly 
to objects, and they need to be implemented for classes that add instance variables. 
They also need to begin with a message to super. The functions available for archiving 
instance variables parallel those for unarchiving; they include NXWriteTypes(), 
NXWritePointO, and NXWriteArrayO, all of which are described elsewhere in this 
chapter. If the object being archived has id instance variables (including those that are 
statically typed to a class), they’re archived as described below. 

In some cases, an object’s id instance variables contain inherent properties of the object 
to which they belong, or they might be necessary for the object to be usable. For 
example, a View’s subview list is an intrinsic part of that View, just as a ButtonCell is 
needed for a Button to work properly. For these kinds of instance variables, the 
object—the View or the Button in the examples mentioned—uses NXWriteObject() 
within its write: method. (Actually, Button objects inherit Control’s write: method, 
which archives the cell instance variable.) The function NXWriteTypes() can also be 
used to archive id instance variables, by specifying the id data type format character. 

In other cases, an object’s id instance variables refer to other objects that act at the 
discretion of the object, such as its target or delegate, or that aren’t inherently part of 
the object. A View’s superview and window instance variables aren’t considered 
intrinsic to the View since you might want to hook up the View to another superview 
or to a different Window. For these kinds of instance variables, the object calls 
NXWriteObjectReference() within its write: method. When archiving a data 
structure that includes objects that have called NXWriteObjectReference(), 
NXWriteRootObject() must be used instead of NXWriteObject(). 

NXWriteObjectReference() specifies that a pointer to nil should be written for the 
object passed in, unless that object is an intrinsic part of some member of the data 
structure being archived. If the object is intrinsic, it will be archived and, after 
unarchiving, the pointer will point to the object. NXWriteRootObject() makes two 
passes through the data structure being written. The first time, it defines the limits of 
the data to be written by including instance variables intrinsic to the data structure and 
by making a note of which objects have been written with 

NXWriteObjectReference(). On the second pass, NXWriteRootObjectO archives 
the data structure. 
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As an example, consider a View that has a Button as one subview and a TextField, 
which is the target of the Button, as another subview. If you archive the Button, its 
ButtonCell will be written. The archived ButtonCell’s target instance variable will 
point to nil. If you archive the View, however, the Button and the TextField will be 
archived since they’re subviews. The ButtonCell will be archived since it’s needed by 
the Button. The ButtonCell’s target instance variable will point to the TextField since 
it’s an intrinsic part of the View. 

RETURN 

NXReadObject() returns the id of the object read. 

EXCEPTIONS 

All functions check whether the typed stream has been opened for reading or for 
writing and raise a TYPED S TREAM_CALLER_ERROR exception with an 
appropriate message if it isn’t correct. For example, if NXReadObject() is called and 
the stream was opened for writing, an exception is raised. 

If an error occurs while creating an instance of the appropriate class, NXReadObjectO 
raises a TYPEDSTREAM_CLASS_ERROR. This function also raises a 
TYPEDSTREAM_FILE_INCONSISTENCY exception if the data to be read is not of 
type id. 

If NXWriteObjectO is used to archive a data structure that includes objects with calls 
to NXWriteObjectReference(), a 

TYPEDSTREAM_WRITE_REFERENCE_ERROR exception is raised. 

SEE ALSO 

NXOpenTypedStream(), NXReadArrayO, NXReadTtypeO, NXReadPointQ, and 
NXTypedStreamClassVersionO 


NXReadObjectFromBuffer(), NXReadObjectFromBufferWithZoneO, 
NXWriteRootObjectToBuffer(), NXFreeObjectBuffer() 

SUMMARY Read and write an object to a typed-stream memory buffer 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

id NXReadObjectFromBuffer(const char * buffer, int length) 
id NXReadObjectFromBufferWithZone(const char *buffer , int length, 
NXZone *zone ) 

char *NXWriteRootObjectToBuffer(id object, int * length ) 
void NXFreeObjectBuffer(char *buffer, int length ) 
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DESCRIPTION 

These functions allow you to easily read and write an object to a typed stream on 
memory. They’re particularly useful for archiving an object, writing it to the 
pasteboard, and then unarchiving it from the pasteboard. 

NXWriteRootObjectToBuffer() opens a stream on memory (using 
NXOpenMemoryO) and a corresponding typed stream. It then writes the object given 
as its argument by calling NXWriteRootObject() and closes the typed stream. (See 
the description of NXWriteRootObject() under NXReadObjectO above for more 
information about how the object is written.) NXWriteRootObjectToBuffer() also 
closes the memory stream but retains the buffer, which is truncated to the size of the 
object. NXWriteRootObjectToBuffer() returns the size of the object (in the location 
specified by length ) and a pointer to the buffer itself. 

NXReadObjectFromBuffer() calls NXReadObjectFromBufferWithZone() with 
the default zone as its zone argument. 

NXReadObjectFromBufferWithZoneO opens a stream on memory and a 
corresponding typed stream with its zone set by the NXSetTypedStreamZone() 
function. The buffer and length arguments passed in should be taken from a previous 
call to NXWriteRootObjectToBuffer(). NXReadObjectO is called to read the object 
from the buffer into the zone, after which the streams are closed. 
NXReadObjecFromBufferWithZoneO saves the memory buffer and returns the 
object it reads in the zone specified. Unless you’re going to reread the buffer, you 
should free it using the NXFreeObjectBuffer() function. 

NXFreeObjectBuffer() frees the buffer specified by buffer, which should be length 
bytes long. These arguments should be taken from a previous call to 

NX Wr iteRootObjectToBuffer (). 

RETURN 

NXReadObjectFromBuffer() returns the object it reads from the buffer. 
NXWriteRootObjectToBufferQ returns a pointer to the buffer it creates. 

EXCEPTIONS 

NXReadObjectFromBuffer() and NXReadObjectFromBufferWithZone() raise a 
TYPEDSTREAM _FILE^INCONSISTENCY exception if the data to be read from the 
buffer is not of type id. 

SEE ALSO 

NXOpenMemoryO, NXReadObjectO, and NXOpenTypedStream() 


NXReadObjectFromBufferWithZoneO —> NXReadObjectFromBuffer() 
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NXReadPointO, NXWritePointO, NXReadRect(), NXWriteRectQ, 
NXReadSizeO, NXWriteSizeO 

SUMMARY Read or write NeXT-defined data types to a typed stream 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXReadPoint(NXTypedStream *typedStream, NXPoint *aPoint ) 
void NXWritePoint(NXTypedStream *typedStream , const NXPoint *aPoint ) 
void NXReadRect(NXTypedStream *typedStream, NXRect *aRect ) 
void NXWriteRect(NXTypedStream *typedStream, const NXRect *aRect) 
void NXReadSize(NXTypedStream *typedStream, NXSize *aSize) 
void NXWriteSize(NXTypedStream *typedStream, const NXSize *aSize ) 

DESCRIPTION 

These functions read and write NXPoint, NXSize, or NXRect structures from and to a 
typed stream. They can be used within read: or write: methods for archiving purposes. 
See the description of NXReadObject() in this chapter for more about these methods. 
Functions are also available for reading and writing other data types; they’re listed 
below under “SEE ALSO.” 

Before using a typed stream for reading and writing, it must be opened; see the 
description of NXOpenTypedStream() for details on opening a typed stream. (The 
NXiypedStream type is declared in the header file objc/typedstream.h. The structure 
itself is private since you never need to access its members.) 

NXReadPointO, NXReadSize(), and NXReadRect() take a typed stream as an 
argument and place the data read from the stream into the location specified by the 
second argument. They work through NXReadType(). 

The three corresponding writing functions work through NXWriteType() to write the 
data specified by their second argument to the typed stream. Note that the second 
argument should be a pointer to the data. The following example shows the three kinds 
of structures being written to an already opened typed stream; to read the same data, 
the corresponding reading functions would be called with the same arguments. 

NXPoint zeroPoint = {0.0, 0.0}; 

NXSize rectSize = {100.0, 200.0}; 

NXRect aRect = {zeroPoint, rectSize}; 

NXWritePoint(stream, SzeroPoint); 

NXWriteSize(stream, &rectSize); 

NXWriteRect(stream, &aRect); 
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EXCEPTIONS 

All six functions check whether the typed stream has been opened for reading or for 
writing and raise a TYPEDSTREAM_FILE_INCONSISTENCY exception if the type 
isn’t correct. For example, if NXReadPoint() is called and the stream was opened for 
writing, the exception is raised. 

The functions for reading raise a TYPEDSTREAM_FILE_INCONSISTENCY 
exception if the data to be read is not of the expected type. 

SEE ALSO 

NXOpenl^pedStream(), NXReadTypeQ, NXReadArray(), NXReadObjectQ 


NXReadRect() —> See NXReadPointO 
NXReadSizeQ —» See NXReadPointO 


NXReadTIFFQ, NXWriteTIFF(), NXGetTIFFInfo() 

SUMMARY Read and write TIFF files 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/tiff.h> 

void *NXReadTIFF (int imageNumber, NXStream * stream, NXTIFFInfo *info, 
void *data ) 

void NXWriteTIFF(NXStream * stream , NXImagelnfo *image, void *data) 
int NXGetTIFFInfo(int imageNumber , NXStream * stream, NXTIFFInfo *info) 

DESCRIPTION 

These functions read and write image data that’s been stored in a TIFF file. This file 
format is described in the Tag Image File Format Specification, Revision 5.0 . (See 
“Suggested Reading” in the Technical Summaries manual for information about how to 
obtain the TIFF specification manual.) 

All three functions take a pointer to an NXStream structure as an argument. This 
stream should be opened on a TIFF file. (The NXStream structure is defined in the 
header file streams/streams.h.) 

NXReadTIFF() reads the image data for the image specified by imageNumber from 
the stream . The info argument points to an uninitialized NXTIFFInfo structure, which 
you should allocate on the stack. NXReadTIFFQ calls NXGetTIFFInfoQ to read the 
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information that describes the image into the NXTIFFInfo structure. This structure is 
defined in the header file appkit/tiff.h. The image data will be stored in the memory 
pointed to by data. If data is NULL, memory for the image data will be made available 
using ma!loc(). If an error occurs while reading the data, the error field of the 
NXTIFFInfo structure will be nonzero, and NXReadTIFF() will return NULL. 

NXWriteTIFF() writes an image to the stream so that it can be saved in a TIFF file. 
The NXImagelnfo structure specified by image describes the image to be written, and 
data points to the image data to be written. The NXImagelnfo structure is defined in 

appkit/tiff.h. 

NXGetTIFFInfo() reads the information for the image specified by imageNumber 
from the stream. The information is stored in the uninitialized NXTIFFInfo structure 
pointed to by info , which you should allocate on the stack. This information provides 
enough detail so that you can read the image data when desired, for example to edit it 
programmatically. The total number of bytes for the image is returned unless there is 
an error. If an error occurs, the error field of the NXTIFFInfo structure will have a 
nonzero value and NXGetTIFFInfo() will return 0. 

RETURN 

NXReadTIFF() returns a pointer to the image data read unless an error occurs while 
reading, in which case it returns NULL. 

NXGetTIFFInfoQ returns the number of bytes needed to store the image or 0 if an 
error occurred while reading the image information. 


NXReadTypeO, NXWriteType(), NXReadTypes(), NXWriteTypes() 

SUMMARY Read or write arbitrary data to a typed stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

void NXReadType(NXTypedStream *typedStream, const char *type, void *data) 
void NXWriteType(NXTypedStream *typedStream, const char *type, 
const void *data ) 

void NXReadTypes(NXTypedStream *typedStream, const char * types ,...) 
void NXWriteTypes(NXTypedStream *typedStream, const char * types ,...) 

DESCRIPTION 

These functions read and write strings of data from and to a typed stream. They can be 
used within read: or write: methods for archiving purposes. See the description of 
NXReadObjectQ in this chapter for more about these methods. Functions are also 
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available for reading and writing certain data types; they’re listed below under “SEE 
ALSO.” 


These functions are similar to the NXPrintf() and NXScanf() functions for streams 
(and to the printf() and scanf() standard C functions). Before using a typed stream for 
reading and writing, it must be opened; see the description of NXOpenTypedStream() 
for details on opening a typed stream. (The NXTypedStream type is declared in the 
header file objc/typedstream.h. The structure itself is private since you never need to 
access its members.) 


These four functions take as arguments a pointer to a typed stream, a character string 
indicating the format of the data to be read or written, and the address of the data. The 
format string characters and their corresponding data types listed below are supported. 


Format Character 

c 

s 

i 

f 

d 

@ 

* 

% 

# 

| 

{<type>} 
[<countxtype>] 


Data Type 

char 

short 

int 

float 

double 

id 

char * 

NXAtom (see text below) 

SEL 

class 

(corresponding data won’t be read or written; see below) 

struct 

array 


When writing, the format character specifies that data should be written as a const 
char pointer. When reading, the data is read and then converted to a unique string using 
NXUniqueStringO. This function is described later in this chapter. The “!” identifier 
should only be used on data that’s the same size as an int. The corresponding data item 
from the stream won’t be read or written. 


NXReadType() and NXWriteTypeO read and write the data specified by data as the 
single data type specified by type. The functions NXReadTypesO and 
NXWriteTypes() read and write multiple types of data; the types should be listed in 
types using the appropriate format characters shown above, and matching data should 
be provided in data. This example shows three different data types being written to an 
already open typed stream: 


float aa = 3.0; 
int bb = 5; 
char *cc = "foo"; 

NXWriteTypes(typedStream, "fi*", &aa, &bb, &cc); 
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If NXWriteType() had been used, three lines of code would have been necessary, one 
for each data type. Both functions take pointers to the data to be written, unlike 
printf(). 

To read these three pieces of data from the NXTypedStream, NXReadTypes() would 
be called with the same arguments as shown above for NXWriteTypes(): 

NXReadTypes(typedStream, "fi*", &aa, &bb, &cc); 


EXCEPTIONS 

All four functions check whether the typed stream has been opened for reading or for 
writing and raise a TYPEDSTREAM_FILE_INCONSISTENCY exception if the type 
isn’t correct. For example, if NXReadTypeQ or NXReadiypes() is called and the 
stream was opened for writing, the exception is raised. 

The functions for reading raise a TYPEDSTREAM_FILE_INCONSISTENCY 
exception if the data to be read is not of the expected type. 

SEE ALSO 

NXOpenTypedStreamQ, NXReadObjectQ, and NXReadPoint() 


NXReadTypesQ —» See NXReadTypeQ 


NXReadWordTableQ, NXWriteWordTable() 

SUMMARY Read or write Text object’s word tables 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Text.h> 

void NXReadWordTable(NXZone *zone, NXStream * stream, 
unsigned char **preSelSmart, unsigned char **postSelSmart, 
unsigned char **charCategories, NXFSM **wrapBreaks, int *wrapBreaksCount, 
NXFSM **clickBreaks, int *clickBreaksCount, BOOL *charWrap) 
void NXWriteWordTable(NXStream * stream , const unsigned char *preSelSmart, 
const unsigned char * postSelSmart, const unsigned char *charCategories, 
const NXFSM *wrapBreaks, int wrapBreaksCount, const NXFSM *clickBreaks, 
int clickBreaksCount, BOOL charWrap) 
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DESCRIPTION 


These functions read and write the Text object’s word tables. Given stream, a pointer 
to a stream containing appropriate data, NXReadWordTableQ creates word tables in 
the memory zone specified by zone. Conversely, given references to word table 
structures, NX Write WordTables() records the structures in the stream referred to by 
stream. 

The word table arguments taken by these two functions are identical except for the 
degree of indirection. For each table it will create, NXReadWordTable() takes the 
address of a pointer. When the function returns, these pointers will point to the newly 
created tables. On the other hand, NX Write WordTabIes() takes a pointer to each table 
it will record to the stream. 

preSelSmart and postSelSmart refer to smart cut and paste tables. These tables specify 
which characters preceding or following the selection will be treated as equivalent to a 
space. wrapBreaks refers to a break table, the table that a Text object uses to determine 
word boundaries for line breaks. wrapBreaksCount gives the number of elements in 
the array of NXFSM structures that make up the break table. Similarly, clickBreaks and 
clickBreaksCount refer to a click table, the table that determines word boundaries for 
word selection. Finally, charWrap refers to a flag indicating whether words whose 
length exceeds the Text object’s line length should be wrapped on a 
character-by-character basis. 

Word tables can be set through the defaults system. The global parameter 
NXWordTablesFile determines which word table file an application will use. The value 
for this parameter can either be a file name or the special values “English” or “C”. The 
special values cause built-in tables for those languages to apply. 

EXCEPTIONS 

NXReadWordTable() raises an NX_wordTablesRead exception if it’s unable to open 
stream. NXWriteWordTable() raises an NX_wordTablesWrite exception if it’s 
unable to open stream or if charCategories, wrapBreaks, or clickBreaks is NULL. 


NXReallyFreeO -> See NXCreateHashTableQ 


NXReadWordTable() 
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NXRectClipO, NXRectClipList(), NXRectFill(), NXRectFillListQ, 
NXRectFillListWithGraysO, NXEraseRectO, NXHighIightRect() 

SUMMARY Optimize drawing 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXRectClip(const NXRect *aRect ) 

void NXRectClipList(const NXRect *rects, int count ) 

void NXRectFill(const NXRect *aRect) 

void NXRectFiIlList(const NXRect *rects, int count ) 

void NXRectFillListWithGrays(const NXRect *rects, const float * grays, int count ) 
void NXEraseRect(const NXRect *aRect) 
void NXHighlightRect(const NXRect *aRect) 

DESCRIPTION 

These functions provide efficient ways to carry out common drawing operations on 
rectangular paths. 

NXRectClipO intersects the current clipping path with the rectangle referred to by its 
argument, aRect, to determine a new clipping path. NXRectClipList() takes an array 
of count number of rectangles and intersects the current clipping path with each of 
them. Thus, the new clipping path is the graphic intersection of all the rectangles and 
the original clipping path. Both functions work through the rectclip operator. After 
computing the new clipping path, the current path is reset to empty. 

NXRectFiIl() fills the rectangle referred to by its argument with the current color. 
NXRectFillList() fills a list of count rectangles with the current color. Both work 
through the rectfill operator. 

NXRectFillListWithGraysO takes a list of count rectangles and a matching list of 
count gray values. The first rectangle is filled with the first gray, the second rectangle 
with the second gray, and so on. There must be an equal number of rectangles and gray 
values. The rectangles should not overlap; the order in which they’ll be filled can’t be 
guaranteed. This function alters the current color of the current graphics state, setting 
it unpredictably to one of the values passed in grays. 

As its name suggests, NXEraseRect() erases the rectangle referred to by its argument, 
filling it with white. It does not alter the current color. 

NXHighlightRectO uses the compositerect operator to highlight the rectangle 
referred to by its argument. Light gray becomes white, and white becomes light gray. 
This function must be called twice, once to highlight the rectangle and once to 
unhighlight it; the rectangle should not be left in its highlighted state. When not 
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drawing on the screen, the compositing operation is replaced by one that fills the 
rectangle with light gray. 


SEE ALSO 

NXSetRectQ, NXUnionRect() 


NXRectClipList() -> See NXRectCIipO 
NXRectFillO -> See NXRectCIipO 
NXRectFillListO -> See NXRectCIipO 
NXRectFillListWithGraysO -> See NXRectCIipO 


NXRedComponentO? NXGreenComponent(), NXBlueComponent(), 
NXCyanComponentO, NXMagentaComponentO, NXYellowComponent(), 
NXBlackComponent(), NXHueComponent(), NXSaturationComponent(), 
NXBrightnessComponentO, NXGrayComponent(), NXAlphaComponentO 

SUMMARY Isolate one component of a color 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

float NXRedComponent(NXColor color ) 
float NXGreenComponent(NXColor color) 
float NXBlueComponent(NXColor color ) 
float NXCyanComponent(NXColor color) 
float NXMagentaComponent(NXColor color) 
float NXYellowComponent(NXColor color) 
float NXBlackComponent(NXColor color) 
float NXHueComponent(NXColor color) 
float NXSaturationComponent(NXColor color) 
float NXBrightnessComponent(NXColor color) 
float NXGrayComponent(NXColor color) 
float NXAlphaComponent(NXColor color) 

DESCRIPTION 

Each of these functions takes an NXColor structure as an argument and returns the 
value of one component of the color, as indicated by the function name. 
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RETURN 


Each functions returns a component of the color passed as an argument. The function 
name indicates which component is returned. NXAlphaComponent() returns 
NX_NOALPHA if a coverage component is not specified for the color. Otherwise, all 
return values lie in the range 0.0 through 1.0. 

SEE ALSO 

NXChangeRedComponent(), NXSetColor(), NXConvertRGBAToColor(), 
NXConvertCoIorToRGBAQ, NXEqualColorQ, NXReadColorQ 


NXRegisterDefaults(), NXGetDefauItValueO, NXReadDefault(), 
NXRemoveDefault(), NXSetDefault(), NXUpdateDefault(), 
NXUpdateDefaultsO, NXWriteDefauItO, NXWriteDefaults(), 
NXSetDefaultsUser() 

SUMMARY Set or read default values 

LIBRARY libdb.a 

SYNOPSIS 

#import <defaults.h> 

int NXRegisterDefaults(const char * owner, const NXDefaults Vector vector) 
const char *NXGetDefault Value (const char * owner, const char *name) 
const char *NXReadDefault(const char * owner, const char *name) 
int NXRemoveDefault(const char * owner, const char *name ) 
int NXSetDefault(const char * owner, const char *name, const char *value) 
const char *NXUpdateDefault(const char *owner, const char *name) 
void NXUpdateDefaults(void) 

int NXWriteDefault(const char *owner, const char *name, const char *value) 
int NXWriteDefaults(const char * owner, NXDefaults Vector vector ) 
const char *NXSetDefaultsUser(const char *newUser) 

DESCRIPTION 

Through the defaults system, you can allow users to customize your application to 
match their preferences by specifying values for default parameters. Each user has a 
defaults database for storing these default values; it’s named .NeXTdefaults and 
resides in ~/.NeXT. 

The defaults registration table allows an application to efficiently read default values 
for a set of parameters without having to open and close the .NeXTdefaults database 
to obtain each value. The table consists of a list of pairs; each pair is composed of a 
parameter name and a corresponding default value. The registration table is created at 
run time by opening the database once to read default values for the parameters the 
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application will use. Every application should create its registration table early in the 
program, before any default values are needed. 

To create this table, call NXRegisterDefaultsO and give it two arguments: A character 
string specifying the name of an application, or owner, and an NXDefaultsVector 
structure. Like the registration table, this structure consists of a list of pairs of 
parameter names and default values. (It’s defined in the header file defaults.h.) 

The NXDefaults Vector structure serves two purposes. First, it provides a complete list 
of all parameters that the application will use. Values for all the parameters specified 
are placed in the registration table at once, so the database doesn’t need to be opened 
and closed for subsequent uses of the parameters. (However, if the application later 
asks for values for parameters that aren’t registered, the database will be opened, read, 
and closed again.) Second, the structure allows the programmer to suggest values for 
the parameters. These values are used if the user hasn’t stated a preference for a 
specific value. 

If the defaults database doesn’t exist when NXRegisterDefaultsO is called, it’s 
automatically created and placed in the .NeXT directory; the directory is also created 
if necessary. 

A good place to call NXRegisterDefaultsO is in the initialize method of the class that 
will use the parameters. The following example registers the values in 
WriteNowDefaults for the owner WriteNow: 

+ initialize 
{ 

static NXDefaultsVector WriteNowDefaults = { 

{"NXFont", "Helvetica"}? 

{"NXFontSize", "12.0"}, 

{NULL} 

} ; 


NXRegisterDefaults{"WriteNow", WriteNowDefaults); 
return self; 

} 

NXRegisterDefaultsO creates a registration table that contains a value for each of the 
parameters listed in the NXDefaults Vector structure. (Note that NULL is used to signal 
the end of the NXDefaults Vector structure.) This value will be the one listed in the 
structure if there’s no value for that parameter in the database, as described below. 

A user’s database may contain values for parameters stored multiple times, each with a 
different owner. For example, the NXFont parameter can have the value Ohlfs with a 
GLOBAL owner. Times for the owner WriteNow, and Courier for the owner Mail. 
When searching a user’s database for the parameters listed in the NXDefaults Vector 
structure, NXRegisterDefaultsO ignores values owned by an application different 
from the one used as its argument. If it finds a parameter and owner that matches those 
passed to it as arguments, the corresponding value from the user’s database rather than 
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the value from the NXDefaults Vector structure is placed in the registration table. If no 
parameter-owner match is found, NXRegisterDefauIts() searches the database’s 
global parameters—that is, those owned by GLOBAL—for a match, and, if it finds one, 
places the corresponding value in the registration table. If a parameter isn’t found in 
the user’s database, the parameter-value pair listed in the NXDefaults Vector structure 
is placed in the registration table. 

Note: When creating their own parameters, applications should use the full market 
name of their product as the owner of the parameter to avoid colliding with already 
existing parameters. Noncommercial applications might use the name of the program 
and the author or institution. 

If the application was launched from the command line, any parameter values specified 
there will be used, overriding values listed in the database and the NXDefaults Vector 
structure. 

To summarize, this is the precedence ordering used to obtain a value for a given 
parameter for the registration table: 

1. The command line 

2. The defaults database, with a matching owner 

3. The defaults database, with the owner listed as GLOBAL 

4. The NXDefaults Vector structure passed to NXRegisterDefaults() 

When your program needs to use a default value, you’ll typically call 
NXGetDefaultValue(). This function takes an owner and name of a parameter as 
arguments and returns a char pointer to the default value for that parameter. 
NXRegisterDefaults() should already have been called, so NXGetDefaultValue() first 
looks in the registration table, where usually it will find a matching parameter and 
value. If NXGetDefaultValueO doesn’t find a match in the registration table (which 
would only be the case if you hadn’t listed all parameters when you called 
NXRegisterDefaultsO), it searches the .NeXTdefaults database for the owner and 
parameter. If still no match is found, it searches for a matching global parameter, first 
in the registration table and then in the database. If the value is found in the database 
rather than the table, NXRegisterDefaultsO registers that value for subsequent use. 

Occasionally, you may want to search only the database for a default value and ignore 
the command line and the registration table. For example, you might want a value that 
another application may have changed after the table was created. In these rare cases 
call NXReadDefault(), which takes an owner and the parameter as arguments and 
looks in the database for an exact match. It doesn’t look for a global parameter unless 
GLOBAL is specified as the owner. If a match is found, a char pointer to the default 
value is returned; if no value is found, NULL is returned. After obtaining a value from 
the database with NXReadDefault(), you may want to write it into the registration 
table with NXSetDefault(). 

NXSetDefaultO takes as arguments an owner, the name of a parameter, and a value for 
that parameter. The parameter and its default value are placed in the registration table, 
but they aren’t written into the .NeXTdefaults database. 
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NXRemoveDefaultO removes the specified default value from the database. 

NXWriteDefault() writes the value and default parameter specified as its arguments 
into the database and places them in the registration table. Similarly, 
NXWriteDefaultsO writes a vector of defaults into the database and registers it. Both 
NXWriteDefault() and NXWriteDefaultsO return the number of successfully written 
values. To maximize efficiency, you should use one call to NXWriteDefaultsO rather 
than several calls to NXWriteDefault() to write multiple values. This will save the 
time required to open and close the database each time a value is written. 

Since other applications (and the user) can write to the database, at various points the 
database and the registration table might not agree on the value of a given parameter. 
You can update the registration table with any changes that have been made to the 
database since the table was created by calling NXUpdateDefault() or 
NXUpdateDefaults(). Both functions compare the table and the database. If a value 
is found in the database that is newer than the corresponding value in the registration 
table, the new value is written into the registration table. 

NXUpdateDefault() updates the value for the single parameter and owner given as its 
arguments. NXUpdateDefaults(), which takes no arguments, updates the entire 
registration table. It checks every parameter in the registration table, determines 
whether a newer value exists in the database, and puts any newer values it finds in the 
registration table. 

Ordinarily, the defaults database functions access the database belonging to the user 
who started the application. NXSetDefaultsUser() changes the defaults database 
accessed by subsequent calls to these functions. NXSetDefaultsUser() accepts the 
name of a user whose database you wish to access; it returns a pointer to the name of 
the user whose defaults database was previously set for access by these functions. All 
entries in the registration table are purged; use NXGetDefaultValue() or 
NXRegisterDefaults() to get the new user’s defaults for your application. When 
NXSetDefaultsUsers() is called, the user who started the application must have 
appropriate access (read, write, or both) to the defaults database of the new user. This 
function is generally called in applications intended for use by a superuser who needs 
to update defaults databases for a number of users. 

RETURN 

NXRegisterDefaults() returns 0 if the database couldn’t be opened; otherwise it 
returns 1. 

NXGetDefaultValue() returns a char pointer to the requested default value or 0 if the 
database couldn’t be opened. 

NXReadDefauIt() returns a char pointer to the default value; if a value is not found, 
NULL is returned. 

NXRemoveDefaultO returns 1 or 0 if the default couldn’t be removed. 
NXSetDefault() returns 1 if it successfully set a default value and 0 if not. 
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NXUpdateDefault() returns the new value or NULL if the value did not need to be 
updated. 

NXWriteDefaultQ returns 1 unless an error occurs while writing the default, in which 
case it returns 0. 

NXWriteDefaults() returns the number of successfully written default values. 

NXSetDefaultsUser() returns the login name of the user whose defaults database was 
being accessed before the function was called. 


NXRegisterErrorReporter(), NXRemoveErrorReporter(), NXReportError() 

SUMMARY Define an error reporter 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/errors.h> 

void NXRegisterErrorReporter(int min, int max, 
void (*/?roc)(NXHandler *errorState )) 
void NXRemoveErrorReporter(int code) 
void NXReportError(NXHandler *errorState ) 

DESCRIPTION 

These three functions set up an error reporting procedure, which typically includes 
writing a message to stderr. When an error is raised (using NX_RAISE()), each of the 
nested error handlers are notified successively until one can handle the error without 
forwarding it to the next level. This handler executes its error handling code, which 
usually includes calling NXReportError(). 

NXReportError()’s errorState argument contains information about the error, 
including an error code that identifies the error. (The NXHandler structure is defined 
in the header file streams/error.h.) NXReportError() uses this error code to search 
the codes for which error reporters have been registered (see below). When it finds a 
match, it calls the corresponding procedure. If no matching error code is found, an 
unknown error code message is written to stderr. 

The Application Kit registers its error reporters in the initialize class method of the 
Application object. Other applications that subclass Application will use these 
reporters by default, but they can also define their own set of errors and a reporter. To 
create your own range of error codes and corresponding error messages, call 
NXRegisterErrorReporter(). Its first two arguments define the range of numbers you 
will use as error codes. Applications that are defining their own reporter should begin 
their range at NX_APPBASE. The third argument points to the procedure that matches 
an error code in that range with an error message. 
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NXRemoveErrorReporterO removes the error reporter that had been assigned to the 
error code passed in as its argument. 


SEE ALSO 

NX RAISEQ, NXDefaultTopLevelErrorHandlerQ 


NXRegisterPrintfProcO 

SUMMARY Register a procedure for formatting data written to a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

void NXRegisterPrintfProc(char/<9rra<2tC/z<2r, NXPrintfProc *proc, void *procData ) 
DESCRIPTION 

NXRegisterPrintfProc registers formatChar, a format character that corresponds to 
*proc, which is a pointer to a function of type NXPrintfProc. The type definition for 
an NXPrintfProc function is: 

typedef void NXPrintfProc (NXStream *stream, void *item, 

void *prodCata) 


formatChar can be any of the characters “vVwWyYzZ”; other characters are reserved 
for use by NeXT. procData represents client data that will be blindly passed along to 
the function. 

After calling NXRegisterPrintfProcO, formatChar can be used in a format string for 
the NXPrintf() or NXYPrintf() functions. When these functions encounter 
formatChar in a format string, proc will be called to format the corresponding argument 
passed to NXPrintfQ. For example: 


tabOver(NXStream stream, void *item, void *data) 
{ 

} 

NXRegisterPrintfProc('v', StabOver, NULL) 
NXPrintf(myStream, "%v", itemOne) 
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This code registers “v” as the formatting character for tabOver(); with the NULL 
argument, no client data will be passed to the tabOver() function. NXPrintf() then 
passes the variable itemOne to tabOver for formatting, which formats the item and 
places it in myStream. 

SEE ALSO 
NXPutcQ 


NXRemoteMethodFromSelO, NXResponsibleDelegate() 

SUMMARY Match an Objective-C method and a receiver to a remote message 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/ Listener.h> 

NXRemoteMethod *NXRemoteMethodFromSel(SEL aSelector , 

NXRemoteMethod * methods) 

id NXResponsibleDelegate(Listener *aListener, SEL aSelector) 

DESCRIPTION 

These two functions are used within subclasses of the Listener class. When you define 
a Listener subclass using the msgwrap utility, calls to these functions are generated 
automatically. 

NXRemoteMethodFromSelO looks up the aSelector method in a table of remote 
methods that have been declared for the Listener subclass. The second argument, 
methods , is a pointer to the beginning of the table. A pointer to the table entry for the 
aSelector method is returned. 

NXResponsibleDelegateO returns the id of the object that responds to aSelector 
remote messages received by aListener. That object will be the Listener’s delegate, or 
the delegate of the Listener’s delegate. A Listener normally entrusts the remote 
messages it receives to its delegate, but if its delegate has a delegate of its own, the 
Listener defers to that object. Thus if the Application object is the Listener’s delegate, 
the Application object’s delegate will be given the first chance to respond to aSelector 
messages. 

RETURN 

NXRemoteMethodFromSelO returns a pointer to the entry for the aSelector method 
in a table of remote methods kept by a Listener subclass, or NULL if there is no entry 
for the method. 
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NXResponsibleDelegate() returns the delegate that responds to aSelector remote 
messages received by aListener. If the delegate of aListener's delegate can respond to 
aSelector messages, it is returned. If not and aListener' s delegate can respond to 
aSelector messages, it is returned. If neither delegate responds to aSelector messages 
(or aListener doesn’t have a delegate), nil is returned. 


NXRemoveDefaultO —> See NXRegisterDefaults() 
NXRemoveErrorReporter() -> See NXRegisterErrorReporter() 
NXReportError() —> See NXRegisterErrorReporter() 
NXResetErrorData() —> See NXAllocErrorData() 
NXResetHashTable() —> See NXCreateHashTableO 
NXResetUserAbort() —> See NXUser Abort() 
NXResponsibleDelegateQ —> See NXRemoteMethodFromSel() 


NXRunAlertPanel(), NXGetAlertPanel(), NXFreeAlertPanel() 

SUMMARY Create or free an attention panel 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Panel.h> 

int NXRunAlertPanel(const char * title , const char *msg, const char *defaultButton, 
const char *alternateButton, const char *otherButton ,...) 
id NXGetAlertPanel(const char * title, const char *msg, const char *jirstButton, 
const char *alternateButton, const char *otherButton, ...) 
void NXFreeAlertPanel(id alertPanel ) 

DESCRIPTION 

NXRunAlertPanel() and NXGetAlertPanel() both create an attention panel that alerts 
the user to some consequence of a requested action; the panel may also let the user 
cancel or modify the action. NXRunAlertPanel() creates the panel and runs it in a 
modal event loop; NXGetAlertPanel() returns the id of a panel that you can use in a 
modal session. 
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These functions take the same set of arguments. The first argument is the title of the 
panel, which should be at most a few words long. The default title is “Alert”. The next 
argument is the message that’s displayed in the panel. It can use printf()-style 
formatting characters; any necessary arguments should be listed at the end of the 
function’s argument list (after the otherButton argument). For more information on 
formatting characters, see the UNIX manual page for printf(). 

There are arguments to supply titles for up to three buttons, which will be displayed in 
a row across the bottom of the panel. The panel created by NXRimAlertPaneI() must 
have at least one button, which will have the symbol for the Return key; if you pass a 
NULL title to the other two buttons, they won’t be created. If NULL is passed as the 
defaultButton, “OK” will be used as its title. The panel created by NXGetAlertPanel() 
doesn’t have to have any buttons. If you supply a title for firstButton, it will be 
displayed with the symbol for the Return key. 

NXRunAlertPanel() not only creates the panel, it puts the panel on screen and runs it 
using the runModalFor: method defined in the Application class. This method sets up 
a modal event loop that causes the panel to remain on screen until the user clicks one 
of its buttons. NXRunAlertPanel() then removes the panel from the screen list and 
returns a value that indicates which of the three buttons the user clicked: 
NX_ALERTDEFAULT, NX_ALERTALTERNATE, or NX_ALERTOTHER. (If an 
error occurred while creating the panel, NX_ALERTERROR is returned.) For 
efficiency, NXRunAlertPanel() creates the panel the first time it’s called and reuses it 
on subsequent calls, reconfiguring it if necessary. 

NXGetAlertPanel() doesn’t set up a modal event loop; instead, it returns the id of a 
panel that can be used to set up a modal session. A modal sessions is useful for 
allowing the user to interrupt the program. During a modal session, you can perform 
activities while the panel is displayed and check at various points in your program 
whether the user has clicked one of the panel’s buttons. 

To set up a modal session, send the Application object a beginModalSession:for: 
message with the id returned by NXGetAlertPanel() as its second argument. When 
you want to check if the user has clicked one of the panel’s buttons, use 
runModalSession:. To end the modal session, use endModalSession:. When you’re 
finished with the panel created by NXGetAlertPanel(), you must free it by calling 
NXFreeAlertPanel(). This function takes the id returned by NXGetAlertPaneI() as 
its only argument. 

RETURN 

NXRunAlertPanelO returns a constant that indicates which button in the attention 
panel the user clicked. 

NXGetAlertPaneI() returns the id of an attention panel for use in a modal session. 
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NXSaturationComponentO —> See NXRedComponent() 

NXSaveToFile() —> See NXOpenMemoryO 

NXScanALine(), NXDrawALine() 

SUMMARY Calculate or draw line of text (in Text object) 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Text.h> 

int NXScanALine(id self, NXLaylnfo * layInfo) 
int NXDrawALine(id self, NXLaylnfo *laylnfo) 

DESCRIPTION 

A Text object calls the first two functions to calculate and draw a line of text. Each 
function’s first argument is a reference to the Text object’s id. The second argument is 
an NXLaylnfo structure, which is defined in the header file appkit/Text.h. 

To determine the placement of characters in a line, NXScanALine() takes into account 
line width, text alignment, font metrics, and other data from the Text object. It stores 
the results of its calculations in global variables. 

A Text object calls NXDrawALineO to draw a line of text. The global variables set by 
NXScanALineQ provide NXDrawALineO with the information it needs to draw each 
line of text. 

RETURN 

NXScanALine() returns 1 only if a word’s length exceeds the width of a line and the 
Text object’s charWrap instance variable is NO. Otherwise, it returns 0. 

NXDrawALineO has no significant return value. 


NXScanfQ -> See NXPutcQ 
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NXSeekQ, NXTellQ, NXAtEOSQ 


SUMMARY Set or report current position in a stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streams.h> 

void NXSeek(NXStream * stream, long offset, int ptrName ) 
long NXTeII(NXStream * stream) 

BOOL NXAtEOS(NXStream * stream) 

DESCRIPTION 

These functions set or report the current position in the stream given as an argument. 
This position determines which data will be read next or where the next data will be 
written since the functions for reading and writing to a stream start from the current 
position. 

NXSeek() sets the position offset number of bytes from the place indicated by ptrName, 
which can be NX_FROMSTART, NX_FROMCURRENT, or NX_FROMEND. 

NXTeIl() returns the current position of the buffer. This information can then be used 
in a call to NXSeek(). 

The macro NXAtEOS() evaluates to TRUE if the end of a stream has been reached. 
Since streams opened for writing don’t have an end, this macro should only be used 
with streams opened for reading. 

Since position within a Mach port stream is undefined, NXSeek() and NXTell() 
shouldn’t be called on a Mach port stream. These functions also shouldn’t be used on 
a typed stream. The NX_CANSEEK flag (defined in the header file 
streams/streams.h) can be used to determine if a given stream is seekable. 

RETURN 

NXTell() returns the current position of the buffer. 

NXAtEOS() evaluates to TRUE if the end of the stream has been detected and to 
FALSE otherwise. 

EXCEPTIONS 

NXSeekO and NXTell() raise an NX_illegalStream exception if the stream passed in is 
invalid. 

NXSeek() raises an NX_illegalSeek exception if offset is less than 0 or greater than the 
length of a reading stream. This exception will also be raised if ptrName is anything 
other than the three constants listed above. 
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NXSetColorQ 


SUMMARY Set the current color 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/color.h> 

void NXSetColor(NXColor color) 

DESCRIPTION 

This function uses PostScript operators to make color the current color of the current 
graphics state. If color includes a coverage component (if NXAlphaComponent() 
returns anything but NX_NOALPHA), it also sets the current coverage. However, 
coverage will not be set when printing. 

SEE ALSO 

NXEqualCoIor(), NXConvertRGBAToColor(), NXConvertColorToRGBA(), 
NXRedComponent(), NXChangeRedComponentO, NXReadColorQ 


NXSetDefault() —> See NXRegisterDefaults() 
NXSetDefauItsUser() —> See NXRegisterDefaults() 
NXSetExceptionRaiser() —> See NXDefaultExceptionRaiserQ 


NXSetGStateO, NXCopyCurrentGStateO 

SUMMARY Set or copy current graphics state object 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/publicWraps.h> 

void NXSetGState(int gstate ) 

void NXCopyCurrentGState(int gstate) 


NXSetColor() 
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DESCRIPTION 


These functions set the current PostScript graphics state. 

NXSetGState() is a C function cover for the PostScript setgstate operator. It sets the 
current graphics state to that specified by gstate. 

NXCopyCurrentGStateO takes a snapshot of the current graphic state and assigns it 
the number gstate. Generally, a snapshot should be taken only when the current path 
is empty and the current clip path is in its default state. 


NXSetRect(), NXOffsetRect(), NXInsetRectO, NXIntegralRect(), 
NXDivideRect() 

SUMMARY Modify a rectangle 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

void NXSetRect(NXRect * aRect, NXCoord x, NXCoord y, NXCoord width, 
NXCoord height ) 

void NXOffsetRect(NXRect *aRect, NXCoord dx, NXCoord dy) 
void NXInsetRect(NXRect *aRect, NXCoord dx, NXCoord dy) 
void NXIntegraIRect(NXRect *aRect) 

NXRect *NXDivideRect (NXRect *aRect, NXRect *bRect, NXCoord slice, int edge ) 
. DESCRIPTION 

These functions modify the aRect argument. It’s assumed that all arguments are 
expressed within the same coordinate system. 

The first function, NXSetRect(), sets the values in the NXRect structure specified by 
its first argument, aRect, to the values passed in the other arguments. It provides a 
convenient way to initialize an NXRect stmcture. 

The next two functions, NXOffsetRect() and NXInsetRectO, are illustrated in Figure 
3-3. 


3-116 Chapter 3: C Functions 



\ 

dy 

' 

dx w i | „ dx 

i 

i 

i 

i 

i 

i 

i 

i 

i 

r 1 

dy 


NXInsetRectQ 



Figure 3-3. Inset and Offset Rectangles 


NXOffsetRectO shifts the location of the rectangle by dx along the x-axis and by dy 
along the y-axis. NXInsetRectQ alters the rectangle so that the two sides that are 
parallel to the y-axis are inset by dx and the two sides parallel to the x-axis are inset by 
dy. 

NXIntegralRect() alters the rectangle so that none of its four defining values (x, y, 
width, and height) have fractional parts. The values are raised or lowered to the nearest 
integer, as appropriate, so that the new rectangle completely encloses the old rectangle. 
These alterations ensure that the sides of the new rectangle lie on pixel boundaries, if 
the rectangle is defined in a coordinate system that has its coordinate origin on the 
comer of four pixels and a unit of length along either axis equal to one pixel. If the 
rectangle’s width or height is 0 (or negative), it’s set to a rectangle with origin at (0.0, 
0.0) and with 0 width and height. 

NXDivideRect() divides a rectangle in two. It cuts a slice off the rectangle specified 
by aRect to form a new rectangle, which it stores in the stmcture specified by hRect. 
The rectangle specified by aRect is modified accordingly. The size of the slice taken 
from the rectangle is indicated by slice; it’s taken from the side of the rectangle 
indicated by edge. The values for edge can be: 

0 The slice is made parallel to the y-axis, along the side with the smallest x 
coordinate values. 

1 The slice is made parallel to the x-axis, along the side with the smallest y 
coordinate values. 

2 The slice is made parallel to the y-axis, along the side with the greatest x 
coordinate values. 

3 The slice is made parallel to the x-axis, along the side with the greatest y 
coordinate values. 
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RETURN 


NXSetRect(), NXOffsetRect(), NXInsetRectO, and NXIntegralRect() have no 
significant return values. NXDivideRectO returns a pointer to the new rectangle, 
bRect. 


SEE ALSO 

NXUnionRect(), NXMouselnRectQ 


NXSetServicesMenuItemEnabled(), NXIsServicesMenuItemEnabled() 

SUMMARY Determine whether an item is included in Services menus 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Listener.h > 

int NXSetServicesMenuItemEnabled(const char *item, BOOL flag) 

BOOL NXIsServicesMenuItemEnabled(const char *item) 

DESCRIPTION 

NXSetServicesMenuItemEnabled() is used by a service-providing application to 
determine whether the Services menus of other applications will contain the item 
command enabling users to request its services. If flag is YES, the Application Kit will 
build Services menus for other applications that include the item command. If flag is 
NO, item won’t appear in any application’s Services menu, item should be the same 

character string entered in the “Menu Item:” field of the_services section. All service 

providers are required to have this section. 

Service-providing applications should let users decide whether the Services menus of 
other applications they use should include the item command. 

RETURN 

NXSetServicesMenuItemEnabled() returns 0 if it’s successful in enabling or 
disabling the item command, and a number other than 0 if not. 
NXIsServicesMenuItemO returns YES if item is currently enabled, and NO if it’s not. 


NXSetTopLevelErrorHandler() —» See NXDefaultTopLevelErrorHandler() 
NXSetTypedStreamZone() -a See NXGetTypedStreamZoneO 
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NXSetUncaughtExceptionHandler(), NXGetUncaughtExceptionHandler() 

SUMMARY Handle uncaught exceptions 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <objc/error.h > 

void NXSetUncaughtExceptionHandIer(NXUncaughtExceptionHandler *proc) 
NXUncaughtExceptionHandler *NXGetUncaughtExceptionHandler(void) 

DESCRIPTION 

These macros provides a means of handling exceptions that are raised outside of an 
NX_DURING...NX_ENDHANDLER construct. You can use the Application object’s 
default procedure, or you can define your own handler using 

NXSetUncaughtExceptionHandler(). 

If proc is NULL or if you never call NXSetUncaughtExceptionHandler(), your 
program will use the Application object’s default procedure. This function writes an 
uncaught exception message to stderr if the application was launched from a terminal. 
If the application was launched by the Workspace Manager, the message is written 
using syslogO with the priority set to LOG_ERR; this message will normally appear in 
the Workspace Manager’s console window. The default uncaught exception handler 
then calls the function pointed to by NXTopLevelErrorHandler() and passes it any 
data about the exception supplied by NX_RAISE(), which was called when the 
exception occurred. (See the description of NX_RAISE().) If you haven’t defined 
your own top-level error handler, the program exits. 

To create your own handler, you define an exception handling function and give the 
name of that function as an argument to NXSetUncaughtExceptionHandler(). 
Subsequent calls to NXGetUncaughtExceptionHandler() will return a pointer to the 
function. These two macros are defined in the header file streams/error.h. 

SEE ALSO 

NX_RAISE(), NXDefaultTopLevelErrorHandler() 


NXSizeBitmapQ -> See NXImageBitmapO 


NXSetUncaughtExceptionHandler() 
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NXStreamCreateFromZoneO, NXStreamCreate(), NXStreamDestroyO, 
NXDefaultReadO, NXDefaultWriteO, NXFill(), NXChangeBuffer() * 

SUMMARY Support a user-defined stream 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <streams/streamsimpl.h> 

NXStream *NXStreamCreateFromZone(int mode, int createBuf, NXZone *zone ) 

NXStream *NXStreamCreate(int mode, int createBuf) 

void NXStreamDestroy(NXStream * stream) 

int NXDefauItRead(NXStream * stream , void *buf int count) 

int NXDefaultWrite(NXStream * stream , const void *buf int count) 

int NXFill(NXStream * stream) 

void NXChangeBuffer(NXStream * stream ) 

DESCRIPTION 

These functions need only be used if you implement your own version of a stream. If 
you’re using a memory stream, a stream on a file, a stream on a Mach port, or a typed 
stream, you don’t need the functions described here. Instead, you can just use the 
functions already defined for these types of streams; see the Technical Summaries 
manual for a list of these functions. 

The first argument to NXStreamCreateFromZone(), mode, indicates whether the 
stream to be created will be used for reading or writing or both. It should be one of the 
following constants: NXJREADONLY, NX_WRITEONLY, or NX_READWRITE. 
The argument createBuf specifies whether the stream should be buffered. If it is TRUE, 
a buffer is created of size NX_DEFAULTBUFSIZE, as defined in the header file 
streams/streamsimpl.h. The argument zone specifies the memory zone where you 
allocate memory for the new stream; see NXZoneMalloc() for more on allocating 
zones of memory. When implementing your own version of a stream, you may want to 
provide a function to open such a stream; this function will probably call 
NXStreamCreateFromZoneO, as NXOpenMemoryO, NXOpenPort(), and 
NXOpenFile() do. 

NXStreamCreate() calls NXStreamCreateFromZoneO with the default zone as its 
zone argument. 

NXStreamDestroyO destroys the stream given as its argument, deallocating the space 
it had used. If a buffer had been created for stream, its storage is also freed. To avoid 
losing data, a stream should be flushed using NXFlush() before it’s destroyed. When 
implementing your own version of a stream, you may want to provide a function to 
close such a stream; this function will probably call NXStreamDestroyO, as 
NXCloseOand NXCloseMemoryO do. 


3-120 Chapter 3: C Functions 



NXDefaultReadO and NXDefaultWriteQ read and write multiple bytes of data on a 
stream. NXDefaultReadO reads the next count number of bytes from stream , starting 
at the position specified by the buffer pointer buf: NXDefaultWrite() writes count 
number of bytes to stream , starting at the position specified by buf. These functions 
return the number of bytes read or written. When implementing your own version of a 
stream, you can use these functions with your stream unless you want to perform 
specialized buffer management. If you implement your own versions of these functions 
for reading and writing bytes, they should return the number of bytes read or written. 

When reading from a buffered stream, NXFill() can be called to fill the buffer with the 
next data to be read. Check whether bufjeft is equal to 0 to determine whether all the 
data currently in the buffer has been read. (See the header file streams/streams.h for 
more information about bufjeft, which is part of an NXStream structure.) 

NXChangeBuffer() switches the mode of a stream between reading and writing. If the 
argument stream had been defined for reading, this function changes it to a stream that 
can be written to; if stream had been defined for writing, it becomes a stream for 
reading. In both cases, the pointer that points to either the next piece of data to be read 
from the buffer or the next location to which data will be written is realigned 
appropriately. Also, NX_READFLAG and NX_WRITEFLAG are updated to reflect 
the new mode of the stream. 

RETURN 

NXStreamCreateO returns a pointer to the stream it creates. 

NXDefaultReadO and NXDefauItWriteO return the number of bytes read or written. 
NXFill() returns the number of characters read into the buffer. 

EXCEPTIONS 

All functions that take a stream as an argument raise an NXJllegalStream exception if 
the stream passed in is invalid. 

NXFill() raises an NX_illegalRead exception if an error occurs while filling. 

NXChangeBufTer() raises an NXJllegalStream exception if NXJREADFLAG and 
NX_WRITEFLAG have not been set to match the NX_CANREAD and 
NX_CANWRITE flags. 

SEE ALSO 

NXOpenFileQ, NXOpenMemoryO, NXClose(), NXFlush(), NXRead() 


NXStreamDestroyO —> See NXStreamCreateO 
NXStrHashQ -> See NXCreateHashTable() 


NXStreamCreateFromZone() 
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NXStrlsEqualQ -> See NXCreateHashTable() 


NXSystemVersion() 

SUMMARY Return the system version for reading streams 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstreams.h> 

int NXSystemVersion(NXTypedStream * stream) 

DESCRIPTION 

NXSystemVersion returns the NeXT system version used for writing stream. The 
system version is useful if the methods or data types defined for the class of the object 
archived in stream have changed from one version to another, by enabling you to test 
the version and switch code to handle the object depending on the version. This 
function is only useful with streams opened for reading. 

RETURN 

This function returns an integer value corresponding to one of the system version 
constants listed in Chapter 1, “Constants and Data Types.” 


NXTell() See NXSeek() 

NXTextFontInfo() 

SUMMARY Calculate font ascender, descender, and line height 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Text.h> 

void NXTextFontInfo(id/o«f/d, NXCoord * ascender, NXCoord * descender, 
NXCoord HineHeighi) 
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DESCRIPTION 


Given a Font object’s id, NXTextFontInfo() calculates the ascender, descender, and 
line height values for that font, fontld is the Font object’s id. ascender, descender, and 
lineHeight are the addresses that will hold the ascender, descender, and line height 
values after a call to NXTextFontInfo(). 


NXToAsciiO, NXToLower(), NXToUpper() 

SUMMARY Convert NeXTstep-encoded characters 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <NXCType.h> 

unsigned char *NXToAscii(unsigned c) 
int NXToLower(unsigned c) 
int NXToUpper(unsigned c) 

DESCRIPTION 

These functions convert characters encoded in the extended character set defined by 
NeXTStep encoding. They are similar to the standard C library functions toascii(), 
tolower(), and toupper() (see the UNIX manual page for ctype), which operate on 
characters in the ASCII character set. 

NXToLowerO converts an upper-case letter to its lower-case equivalent, and 
NXToUpperO converts a lower-case letter to its upper-case equivalent. If there’s no 
opposite case equivalent—or if the character is already of the desired case—these 
functions return the supplied argument unchanged. 

NXToAsciiO converts its argument to a value that lies within the standard ASCII 
character set. The lower 128 positions in the NeXTStep encoding constitute the ASCII 
character set, so no conversion is required for codes in this range. For the upper 128 
character codes—the extended characters— NXToAsciiO makes these conversions: 


NXToAsciiO 
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Extended Character Converts to 

Agrave, Aacute, Acircumflex, Atilde, Adieresis, Aring A 

Ccedilla C 

Egrave, Eacute, Ecircumflex, Edieresis E 

Igrave, Iacute, Icircumflex, Idieresis I 

Ntilde N 

Ograve, Oacute, Ocircumflex, Otilde, Odieresis, Oslash O 

Ugrave, Uacute, Ucircumflex, Udieresis 
Yacute 
eth, Eth 
Thom, thorn 
fi 
fl 

agrave, aacute, acircumflex, atilde, adieresis, aring 
ccedilla 

egrave, eacute, ecircumflex, edieresis 
AE 

igrave, iacute, icircumflex, idieresis 
ntilde 
Lslash 
OE 

ograve, oacute, ocircumflex, otilde, odieresis, oslash 
ae 

ugrave, uacute, ucircumflex, udieresis 
dotlessi 

yacute, ydieresis 
lslash 
oe 

germandbls 
multiply 
divide 

exclamdown 
quotesingle 

quotedblleft, guillemotleft, quotedblright, guillemotright, quotedblbase 
quotesinglbase 
guilsinglleft 
guilsinglright 
periodcentered 
brokenbar 
bullet 
ellipsis 

questiondown 
onesuperior 
twosuperior 
threesuperior 
emdash 
plusminus 
onequarter 


U 

Y 

TH 

th 

fi 

fl 

a 

c 

e 

AE 

i 

n 

L 

OE 

o 

ae 

u 

i 

y 

1 

oe 

ss 

X 

/ 

I 


? 

1 

2 

3 

+- 

1/4 


(continued) 
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Extended Character 


Converts to 


onehalf 1/2 

threequarters 3/4 

ordfeminine a 

ordmasculine o 


mu, copyright, cent, sterling, fraction, yen, florin, section, currency, 
registered, endash, dagger, daggerdbl, paragraph, perthousand, 
logicalnot, grave, acute, circumflex, tilde, macron, breve, dotaccent, 
dieresis, ring, cedilla, hungarumlaut, ogonek, caron, 


RETURN 

NXToAscii() returns by reference a valid ASCII character. NXToLower() or 
NXToUpper() returns an integer value that represents the converted character. 

SEE ALSO 

NXIsAlphaQ 


NXToLowerO -> See NXToAscii() 

NXTopLevelErrorHandler() —> See NXDefaultTopLevelErrorHandIer() 
NXToUpper() -> See NXToAscii() 
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NXTypedStreamCIassVersion() 


SUMMARY Get the class version number of an archived instance 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/typedstream.h> 

int NXTypedStreamClassVersion(NXTypedStream *typedStream, 
const char *className ) 

DESCRIPTION 

This function returns the class version number of an archived object. Class versioning 
is useful if you create a class, archive an instance of it, then change the class—by 
adding instance variables to it, for example. This function is used in a class’s read: 
method to select the appropriate code for initializing the instance being unarchived. 
This function should be called only on a typed stream opened for reading with 
NXReadObject(). 

NXTypedStreamClassVersionO can be called in your read: method after sending a 
[super read itypedStream] message and before performing version-specific 
initialization. Calling this function doesn’t change the position of the read pointer in 
typedStream. If you need to know the version of an object’s superclass (or any class in 
its inheritence hierarchy), call this function using the name of that class as className. 

For NXTypedStreamClassVersionO to return a non-zero value, you should change the 
class version to a new value whenever you change the class definition. The Object class 
provides two methods for handling class versioning. Object’s setVersion: class 
method can be used in a subclass’s initialize class method to set a new class version 
when you change the instance variables. Object’s version class method returns the 
current version of your class. 

The NXWriteObjectO function automatically archives the class version when it is 
archiving an object. The default version number is 0. Thus if you have previously 
archived instances of a class without setting the version, you can set the version of the 
altered class to any integer value other than 0, then use this function to detect old and 
new instances of the class. 

In the following code example, MyClass’s initialize method sets the class version using 
Object’s setVersion: method: 


@implementation MyClass:MySuperClass 
+ initialize 
{ 

[MyClass setVersion:MYCLASS_CURRENT_VERSION]; 
return self; 

} 
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In the next example, MyClass’s read: method uses version numbers to unarchive old 
and new instances differently: 

- read:(NXTypedStream *)typedStream 
{ 

[super read:typedStream]; 

if (NXTypedStreamClassVersion(typedStream, "MyClass") == 
[MyClass version] { 

/* read code for current version */ 


} 

else { 

/* read code for old version */ 


} 

} 

See the description of NXReadObject() earlier in this chapter for more information 
about archiving. The NXTypedStream type is declared in the header file 
objc/typedstream.h. The structure itself is private since you never need to access its 
members. 

SEE ALSO 

NXReadObjectQ 


NXUngetcQ -> See NXPutcQ 


NXUnionRect(), NXIntersectionRectO 

SUMMARY Compute third rectangle from two rectangles 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

NXRect *NXUnionRect(const NXRect *aRect, NXRect *bRect ) 

NXRect *NXIntersectionRect(const NXRect *aRect, NXRect *bRect ) 

DESCRIPTION 

NXUnionRect() figures the graphic union of two rectangles—that is, the smallest 
rectangle that completely encloses both. It takes pointers to the two rectangles as 
arguments and replaces the second rectangle with their union. If one rectangle has zero 
(or negative) width or height, bRect is replaced with the other rectangle. If both of the 
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rectangles have 0 (or negative) width or height, bRect is set to a rectangle with its origin 
at (0.0, 0.0) and with 0 width and height. 

NXIntersectionRectO figures the graphic intersection of two rectangles—that is, the 
smallest rectangle enclosing any area they both have in common. It takes pointers to 
the two rectangles as arguments. If the rectangles overlap, it replaces the second one, 
bRect , with their intersection. If the two rectangles don’t overlap, bRect is set to a 
rectangle with its origin at (0.0,0.0) and with a 0 width and height. Adjacent rectangles 
that share only a side are not considered to overlap. 

Both functions assume that all arguments are expressed within the same coordinate 
system. 

RETURN 

NXUnionRect() returns its second argument {bRect), a pointer to the union of the two 
rectangles unless both rectangles have 0 (or negative) width or height, in which case it 
returns a pointer to a NULL rectangle. 

If the two rectangles overlap, NXIntersectionRectO returns its second argument 
{bRect), a pointer to their intersection. If the rectangles don’t overlap, it returns a 
pointer to a NULL rectangle. 

SEE ALSO 

NXIntersectsRectO 


NXUniqueStringO, NXUniqueStringWithLength(), 
NXUniqueStringNoCopyO, NXCopyStringBuffer(), 
NXCopyStringBufferFromZoneO 

SUMMARY Manipulate a string buffer 

LIBRARY libsys_s.a 

SYNOPSIS 

#import cobjc/hashtable.h > 

NXAtom NXUniqueString(const char * buffer ) 

NXAtom NXUniqueStringWithLength(const char *buffer, int length) 
NXAtom NXUniqueStringNoCopy(const char *buffer) 
char *NXCopyStringBuffer(const char *buffer) 

char *NXCopyStringBufferFromZone(const char *buffer, NXZone *zone) 
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DESCRIPTION 


The first three functions in this group create unique strings, which are allocated once 
and then can be shared. The fourth and fifth function allocates memory for and returns 
a copy of the given string. 

Unique strings are identified by the type NXAtom, which indicates that they can be 
compared using == rather than strcmp(). NXAtom strings shouldn’t be deallocated or 
modified; the Mach function vm_protect() is used to ensure that the strings are 
read-only. (The type NXAtom is defined in objc/hashtable.h.) 

NXUniqueStringO, NXUniqueStringWithLength(), and 

NXUniqueStringNoCopyO maintain a hash table of unique strings. Each function 
checks if the string passed in is already in the table and if so, returns it. Because a hash 
table is used, the average search time is constant regardless of how many unique strings 
exist. If buffer doesn’t exist in the hash table, NXUniqueStringO and 
NXUniqueStringWithLength() return a pointer to a copy of it as an NXAtom; 
NXUniqueStringNoCopyO inserts the string in the hash table but doesn’t make a copy 
of it. For efficiency, all unique strings are stored in the same area of virtual memory. 

NXUniqueStringO assumes buffer is null-terminated; if it’s NULL, 
NXUniqueStringO returns NULL. NXUniqueStringWithLength() assumes that 
buffer is a non-NULL string of at least length non-NULL characters. 

NXCopyStringBuffer() allocates memory from the default memory zone for a copy of 
buffer. Then buffer , which should be null-terminated, is copied using strcpy(). 
NXCopyStringBufferFromZone() is identical to NXCopyStringBuffer() except that 
memory is allocated from the specified zone. 

RETURN 

NXUniqueStringO and NXUniqueStringWithLength() return a pointer to a copy of 
buffer as an NXAtom. 

NXUniqueStringNoCopyO returns a pointer to the string passed in. 

NXCopyStringBuffer() and NXCopyStringBufferFromZone() return a pointer to a 
copy of buffer. 


NXUniqueStringNoCopyO -a See NXUniqueStringO 
NXUniqueStringWithLength() —> See NXUniqueStringO 
NXUnnameObjectO -a See NXGetNamedObject() 
NXUpdateDefaultO —> See NXRegisterDefaultsO 
NXUpdateDefaultsO —> See NXRegisterDefaultsO 


NXUniqueString() 
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NXU pdateDynamicServicesQ 


SUMMARY Re-register provided services 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Listener.h> 

void NXUpdateDynamicServices(void) 

DESCRIPTION 

NXUpdateDynamicServices() is used by a service-providing application to re-register 
the services it is willing to provide. A list of an application’s dynamic services should 
be maintained in the user’s ~/.NeXT/services directory; this list is syntactically 

identical to the list in the application’s_services section. Thus, an application named 

Foo should maintain its dynamic services in the ~/.NeXT/services/Foo file. Many 
applications do not provide dynamic services; all the services they provide are known 

at compile time, so their services are simply listed in their_services section. If the 

services an application can provide may change at run time, the application can build a 
list of additional services that it is willing to provide and then call 
NXUpdateDynamicServicesO to make these services available. An example of a 
dynamic service provider is Digital Librarian™; when you drag a folder named 
“Business” into its Librarian Services window, the Digital Librarian will update its 
services in order to provide a “Search in Business” service. 


NXUserAborted(), NXResetUserAbortO 

SUMMARY Report user’s request to abort 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/Application.h> 

BOOL NXUserAborted(void) 
void NXResetUserAbort(void) 

DESCRIPTION 

NXUser Aborted() returns YES if the user pressed Command-period since the 
application last got an event in the main event loop, and NO if not. Command-period 
signals the user’s intention to abort an ongoing process. Applications should call this 
function repeatedly during a modal session and respond appropriately if it ever returns 
YES. 
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NXResetUser Abort() resets the flag returned by NXUser Aborted() to NO. It’s called 
in the Application object’s run method before getting each new event. 

RETURN 

NXUser Aborted() returns YES if the user pressed Command-period, and NO 
otherwise. 


NXUserName() —> See NXHomeDireetoryO 
NXVPrintfO See NXPutc() 

NXVScanfO -» See NXPutc'O 
NXWindowList() —> See NXCountWindows() 

NXWriteO -> See NXReadO 
NX Write Array () —> See NXReadArrayO 
NXWriteColor() -a See NXReadCoIorQ 
NXWriteDefault() —> See NXRegisterDefaultsQ 
NXWriteDefaults() —> See NXRegisterDefaults() 

NXWriteObjectO —> See NXReadObject() 
NXWriteObjectReference() -> See NXReadObjectO 
NXWritePoint() -> See NXReadPoint() 

NXWriteRect() -> See NXReadPoint() 

NXWriteRootObjectO —> See NXReadObjectO 
NXWriteRootObjectToBufferO —> See NXReadObjectFromBufferO 
NXWriteSizeO —> See NXReadPointO 
NXWriteTIFFO -» See NXReadTIFF() 

NXWriteTypeO See NXReadTypeO 
NXWriteTypesQ -> See NXReadTypeO 
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NXWriteWordTable() -> See NXReadWordTable() 
NXYellowComponent() —> See NXRedComponentO 
NXZoneCallocO —> See NXZoneMalloc() 
NXZoneFromPtr() —> See NXZoneMaIIoc() 
NXZoneFreeO -> See NXZoneMalloc() 


NXZoneMalIoc(), NXZoneCallocO, NXZoneRealloc(), NXZoneFreeO? 
NXDefaultMallocZoneO? NXCreateZoneO? NXCreateChildZone(), 
NXMergeZoneO? NXDestroyZoneO? NXZoneFromPtrO, NXZonePtrInfo(), 
NXMallocCheckO, NXNameZoneO 

SUMMARY Allocate memory 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <zone.h> 

void *NXZoneMalloc(NXZone *zonep, size_t size ) 
void *NXZoneCalloc(NXZone *zonep , size_t numElems, size_t byteSize) 
void *NXZoneRealIoc(NXZone *zonep, void *ptr, size_t size) 
void NXZoneFree(NXZone *zonep, void *ptr) 

NXZone *NXDefaultMallocZone(void) 

NXZone *NXCreateZone(size_t startSize, size_t granularity, int canFree) 

NXZone *NXCreateChildZone(NXZone *parentZone, size_t startSize, 
size_t granularity, int canFree) 
void NXMergeZone(NXZone *zonep) 
void NXDestroyZone(NXZone *zonep) 

NXZone *NXZoneFromPtr(void *ptr) 
void NXZonePtrInfo(void *ptr) 
int NXMallocCheck(void) 

void NXNameZone(NXZone *zonep, const char *name) 

DESCRIPTION 

These functions allocate and free memory space. They are similar to the standard C 
library malloc() functions, but allow the application writer more control over memory 
placement. By allocating frequently used objects from the same zone, the application 
writer can ensure better locality of reference; this can significantly improve 
performance on a paged virtual memory system. In other words, by grouping certain 
objects close together, you can ensure that consecutive references are less likely to 
result in memory paging activity. 
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To use these functions, you must first create a new zone using NXCreateZone(). You 
pass it a parameter startSize , which is the initial size of the new zone. The parameter 
granularity determines the granularity by which the zone itself grows and shrinks. If 
you are allocating a zone for small items, a good choice for both the initial size and 
granularity might be vm_page_size. The parameter canFree determines whether the 
allocator will free memory within the zone. If canFree is NO, memory cannot be freed 
and the allocator will be as fast as possible; but you will need to destroy the zone to 
reclaim the memory. You can call NXCreateZone() multiple times to create several 
zones. NXCreateZoneO returns a pointer to the newly created zone. 

NXZoneMalloc() allocates size bytes from the zone zonep, and returns a pointer to the 
allocated memory. NXZoneCallocQ allocates enough zeroed memory for numElems 
elements, each with a size of byteSize bytes from the zone zonep , and returns a pointer 
to the allocated memory. NXZoneRealloc() changes the size of the block pointed to 
by ptr to size. The block of memory may be moved, but its contents will be unchanged 
up to the lesser of the new and old sizes. All these functions return NULL upon failure. 

NXCreateChildZoneO creates a new zone which obtains memory from another zone. 
It returns a pointer to the new zone, or NX_NOZONE if you attempt to create a child 
zone from a zone which is itself a child. NXMergeZoneQ merges a child zone back 
into its parent zone. The allocated memory that was within the child zone remains 
valid. 

NXZoneFree() returns memory to the zone from which it was allocated. 
NXDestroyZoneO destroys a zone, and all the memory from the zone is reclaimed. 
NXDefaultMaIlocZone() returns the default zone. This is the zone used by the 
standard C library malloc() function. NXZoneFromPtr() returns the zone for a block 
of memory. The pointer ptr must have been returned from a prior malloc or realloc call. 
NXZonePtrInfo() will print information to stdout about the malloc block for the 
memory indicated by ptr. NXMallocCheck() verifies all internal malloc information, 
and returns zero if there is no error. NXNameZone() names the zone zonep with a copy 
of name. 


NXZonePtrInfo() —> See NXZoneMalloc() 
NXZoneRealloc() —> See NXZoneMallocQ 


NXZoneMalloc() 
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NXADDRESSQ 


SUMMARY Get a pointer to the objects stored in a List 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <objc/List.h> 

. id *NX_ADDRESS(List *aUst) 

DESCRIPTION 

This macro takes a List object aList as its argument and returns a pointer to the first id 
stored in the List. With this pointer, you get direct access to the contents of the List and 
can avoid the overhead of messaging. NX_ADDRESS() therefore provides an 
alternative to List’s objectAt: method for situations where somewhat greater 
performance is required. In general, however, the method is the preferred way of 
accessing the List. 

RETURN 

This macro returns a pointer to the contents of a List object. 

SEE ALSO 

The specification for the List class. 


NX_ASSERT() 

SUMMARY Write an error message 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/nextstd.h> 

void NX_ASSERT(int exp, char *msg) 

DESCRIPTION 

This macro, which is defined in the header file appkit/nextstd.h, writes an error 
message if the program was compiled with the NX_BLOCKASSERTS flag undefined 
and if exp is false. The message msg is written to stderr if the application was launched 
from a terminal. If the application was launched by the Workspace Manager, the 
message is written using syslogQ with the priority set to LOG_ERR. Normally, 
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syslogO writes messages to the Workspace Manager’s console window. See the UNIX 
manual page for syslogO for more information about this function and how to write 
messages to places other than the console window. 

If exp is true, no action is taken. Also, if the NX_BLOCKASSERTS fl a g j s defined, a 
call to NX_ASSERT() has no effect. 


NXEVENTCODEMASKQ 

SUMMARY Convert event type to mask 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <dpsclient/event.h> 

int NX_EVENTCODEMASK(int eventType ) 

DESCRIPTION 

This macro converts an event type, as defined in dpsclient/event.h, to an event mask. 
A window’s event mask determines which types of events the Window Server will 
associate with the window. 

An event mask is an int that stores a set of one-bit flags. (See dpsclient/event.h for a 
list of the predefined event masks.) By using NX_EVENTCODEMASK() to convert 
an event into an event mask, you can easily test an event’s type. For example, assume 
anEvent is a pointer to an event record. You could find out if the record is for a 
keyboard event by converting its type to an event mask and comparing the mask to a 
mask for keyboard events: 

if (NX_EVENTCODEMASK(anEvent->type) & 

(NX_KEYDOWNMASK|NX_KEYUPMASK|NX_FLAGSCHANGEDMASK)){ 

/* anEvent is a keyboard event */ 

} 

RETURN 

This macro returns an integer mask. 


NX FREE() -> See NX MALLOCQ 
NX_HEIGHT() -> See NX_X() 


NX_EVENTCODEMASK() 3-135 



NX MALLOCQ, NX_REALLOC(), NX FREE() 


SUMMARY Allocate memory 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <appkit/nextstd.h> 

type-name *!XX_MAlAjOC(type-name *var, type-name, int num) 
type-name *NX_REALLOC(/y/?e~namc *var, type-name, int num ) 
void NX_FREE(void * pointer ) 

DESCRIPTION 

These macros allocate and free memory space by making calls to the standard C library 
functions malloc(), realloc(), and free(). For more information about these functions, 
see their UNIX manual pages. 

NX_MALLOC() and NX_REALLOC() return a pointer of type type to the argument 
var. The amount of memory these two functions allocate is determined by multiplying 
num (which should be an int) by the number of bytes needed for the data type type. 
NX_REALLOC() should be used to change the size of the object var, just as realloc 
would be used. For convenience, these macros are shown below as they are defined in 
the header file appkit/nextstd.h: 

#define NX_MALLOC(VAR, TYPE, NUM) \ 

((VAR) = (TYPE *) malloc((unsigned)(NUM)*sizeof(TYPE))) 

#define NX_REALLOC(VAR, TYPE, NUM) \ 

((VAR) = (TYPE *) realloc((char *)(VAR), \ 

(unsigned)(NUM)*sizeof(TYPE))) 

NX_FREE() deallocates the space pointed to by pointer. It does nothing if pointer is 
NULL. It’s also defined in appkit/nextstd.h, as shown below: 

#define NX_FREE(PTR) free((char *) (PTR)); 


RETURN 

NX_MALLOC() and NX_REALLOC() return pointers to the space they allocate or 
NULL if the request for space cannot be satisfied. 


NX_MAXX() -> See NX_X() 
NX_MAXY() -> See NX_X() 
NX_MIDX() -> See NX_X() 
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NX_MIDY() -» See NX_X() 


NX PSDEBUG 

SUMMARY Print the current PostScript context 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/nextstd.h> 
void NXPSDEBUG 

DESCRIPTION 

NX_PSDEBUG prints the current Display PostScript context to the standard output 
device, along with the class, object, and method in which the macro appears. This 
macro works only when the application is compiled with DEBUG defined. 


NX_RAISE(), NX_RERAISE(), NX YALRETURN(), NX VOIDRETURN 

SUMMARY Raise an exception 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import cobjc/error.h > 

void NX_RAISE(m? code, const void *datal, const void *data2 ) 

NX RERAISE(void) 

NX VALRETURN(val) 

NX VOIDRETURN 

DESCRIPTION 

These macros initiate the error handling mechanism by alerting the appropriate error 
handler that an error has occurred. Error handlers exist in a nested hierarchy, which is 
created by using any number of nested NX_DURING...NX_ENDHANDLER 
constructs and by defining a top-level error handler. 

The three arguments for NX_RAISE() provide information about the error condition. 
The first argument is a constant that acts as a label for the error. (Error codes used by 
the Application Kit are defined in the header file appkit/errors.h.) The next two 
arguments point to arbitrary data about the error. Within an 

NX_DURING...NX_ENDHANDLER construct, this data is stored in a local variable 
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called NXLocalHandler (which is of type NXHandler, defined in the header file 
streams/error.h). (See the description of NXAllocErrorDataO for more information 
about managing the storage of error data.) NX_RAISE() calls the function pointed to 
by NXGetExceptionRaiserQ; see this function’s description earlier in this chapter. 

By default, an error handler should call NX_RERAISE() when it encounters an error 
that it can’t handle, as shown below. NX_RERAISE() has the same functionality as 
NX_RAISE(), but it’s called with no arguments. Since NX_RERAISE() implies a 
previous call to NX_RAISE(), the error data will already be stored in the local handler, 
eliminating the need for arguments. 

NX_DURING 

/* code that may cause an error */ 

NX_HANDLER 

switch ( /* NXLocalHandler code */ ) 
case 

NX_someErrorCode: 

/* code to execute for’this type of error */ 
default: NX_RERAISE(); 

NX_ENDHANDLER 

NX_VALRETURN() and NX_VOIDRETURN can be used to exit a method or 
function from within the block of code between NX_DURING and NX_HANDLER 
labels. The only legal ways of exiting this block are falling out the bottom or using one 
of these macros. NX_VALRETURN() causes its method (or function) to return val , 
while NX_VOIDRETURN can be used to return from a method (or function) that has 
no return value. Use these macros only within an NX_DURING...NX_HANDLER 
construct. 

SEE ALSO 

NXAllocErrorDataO, NXSetU ncaughtExceptionHandler (), 
NXDefaultTopLevelErrorHandler(), NXRegisterErrorReporterO, 
NXDefaultExceptionRaiser() 


NX REALLOCO -> See NX_MALLOC() 
NX RERAISEO -> See NX RAISE() 


NX VALRETURNO -> See NX RAISE() 
NX VOIDRETURNO -> See NX RAISE() 
NX WIDTHO -> See NX X() 
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NX_X(), NX_Y(), NXWIDTHQ, NX_HEIGHT(), NX_MAXX(), 

NX MAXY(), NX MIDXO, NX_MIDY() 

SUMMARY Query an NXRect structure 

LIBRARY libNeXT_s.a 

SYNOPSIS 

#import <appkit/graphics.h> 

NXCoord NX_X(NXRect *aRect) 

NXCoord NX_Y(NXRect *aRect) 

NXCoord NX_WIDTH(NXRect *aRect) 

NXCoord NX_HEIGHT(NXRect *aRect) 

NXCoord NX_MAXX(NXRect *aRect) 

NXCoord NX JVf AX Y(NXRect *aRect) 

NXCoord NX_MIDX(NXRect *aRect) 

NXCoord NX_MIDY(NXRect *aRect) 

DESCRIPTION 

These macros return information about the NXRect structure referred to by aRect. An 
NXRect structure is defined by a point that locates the rectangle (x and y coordinates) 
and an extent that determines its size (a width and height as measured along the x- and 
y-axes). 

RETURN 

NX_X() and NX_Y() return the x and y coordinates that locate the rectangle. These 
will be the smallest coordinate values within the rectangle. 

NX_HEIGHT() and NX_WIDTH() return the width and height of the rectangle. 

NX_MAXX() and NX_M AXY() return the largest x and y coordinates in the rectangle. 
These are calculated by adding the width of the rectangle to the x coordinate returned 
by NX_X() and by adding the height of the rectangle to the y coordinate returned by 
NX_Y(). 

NX_MIDX() and NX_MIDY() return the x and y coordinates that lie at the center of 
the rectangle, exactly midway between the smallest and largest coordinate values. 

SEE ALSO 
NXSetRectQ 



NX_ZONEMALLOC(), NX_ZONEREALLOC() 


SUMMARY Allocate zone memory 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <appkit/nextstd.h> 

type-name *NX_ZONEMALLOC (NXZone zone, type-name *var, 
type-name, int num) 

type-name *NX_ZONEREALLOC(NXZone zone, type-name *var, 
type-name, int num) 

DESCRIPTION 

These macros allocate and free memory space by making calls to the functions 
NXZoneMaIloc() and NXZoneRealloc(). For more information about these 
functions, see their descriptions earlier in this chapter. 

NX_ZONEMALLOC() and NX_ZONEREALLOC () return a pointer of type 
type-name to the argument var allocated in zone. The amount of memory these two 
macros allocate is determined by multiplying num (which should be an int) by the 
number of bytes needed for the data type type-name. NX_ZONEREALLOC() should 
be used to change the size of the object var, just as realloc() or NXZoneRealloc() 
would be used. For convenience, these macros are shown below as they are defined in 
the header file appkit/nextstd.h: 

#define NX_ZONEMALLOC(Z, VAR, TYPE, NUM) \ 

((VAR) = (TYPE *) NXZoneMalloc((Z), \ 

(unsigned)(NUM)*sizeof(TYPE))) 

fdefine NX_ZONEREALLOC(Z, VAR, TYPE, NUM) \ 

((VAR) = (TYPE *) NXZoneRealloc((Z), (char *)(VAR), \ 

(unsigned) (NUM)*sizeof(TYPE))) 


RETURN 

NX_ZONEMALLOC() and NX_ZONEREALLOC() return pointers to the space 
they allocate or NULL if the request for space cannot be satisfied. 
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Single-Operator Functions 

The Display PostScript system provides a C function interface for each operator in the 
PostScript language. These functions let you easily execute individual PostScript operators 
from your application. Adobe Systems Incorporated provides the primary documentation 
for these operators and for pswrap, the utility that creates a C function for one or more 
PostScript operators. (See “Suggested Reading” in the Technical Summaries manual for 
pswrap and other Display PostScript system documentation.) 

NeXT has added several operators and their corresponding single-operator functions to the 
basic Display PostScript system. The operators are documented in Chapter 4, “PostScript 
Operators,” and the functions are listed below. These functions are provided in the library 

libNeXTs.a. 

In the Display PostScript system, each PostScript operator is represented by two 
single-operator functions (or “procedures,” as they are referred to in Adobe 
documentation), one that takes a context argument and another that assumes the current 
PostScript context. The functions that take a context argument have a “DPS” prefix; those 
that assume the current context have a “PS” prefix. For example, the moveto operator is 
represented by these functions: 

DPSmoveto(DPSContext context, float x, float y) 

PSmoveto(float x, float y) 

To save space, only the single-operator functions prefixed with “PS” are listed here. The 
header file dpsclient/dpswraps.h declares the function prototypes for all single-operator 
functions having the “DPS” prefix; the header file dpsclient/wraps.h declares the 
prototypes for “PS” functions. 

Operand names available in the PostScript language, such as Copy or Sover for the 
composite operator, are defined as symbolic constants for use from C, but in all uppercase 
and preceded by “NX_” (for example, NX_COPY and NX_SOVER). These symbolic 
constants are defined in the NeXT header file dpsNeXT.h, except for the event-related ones, 
which are in dpsclient/event.h and appkit/appkit.h. 

As with the basic Display PostScript single-operator functions, some of the C functions 
listed below have parameters that match the operands of their corresponding PostScript 
operators. For example, the setalpha operator accepts a number on the PostScript operand 
stack, while the C function PSsetalphaQ takes a float as an argument. The functions may 
also have parameters that point to returned values, corresponding to results returned on the 
operand stack by the PostScript operator. The buttondown operator returns a Boolean on 
the stack indicating whether the left mouse button is down; PSbuttondown() has a 
parameter that’s a pointer to a Boolean, which upon return will contain 1 or 0 to indicate 
the status of the mouse button. 

Other C functions have no parameters where their corresponding PostScript operators 
expect operands or leave results on the operand stack. These functions assume that they’ll 
be called with the appropriate objects already on the operand stack, and they’ll leave any 
PostScript objects they generate on the operand stack instead of returning them through 
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parameters. For example, the PSaIphaimage() function requires that you place the 
appropriate operands on the operand stack before calling the function. You can learn which 
operands the function expects by looking at the declaration of the corresponding operator. 

To support the functions that use the operand stack rather than parameters, the Display 
PostScript system has several additional functions for putting values on and getting values 
off the stack: 

Function 

PSsendint() 

PSsendfloat() 

PSsendbooleanQ 
PSsendstringO 

PSgetint() 

PSgetfloat() 

PSgetboolean() 

PSgetstringO 

PSsendintarrayO 
PS sendfloatarray () 

PS sendchararray () 

PSgetintarrayO 
PSgetfloatarrayO 
PSgetchararrayO 

Note the following: 

• In addition to the standard C types, pswrap uses two others: boolean and userobject. 
A boolean variable is an int having either a zero or a nonzero value. The zero value is 
equivalent to the PostScript value false, and the nonzero value is equivalent to the 
PostScript value true. The userobject type is an int that refers to the value returned by 
DPSDefineUserObject(). See Extensions for the Display PostScript System for more 
information on user objects. 

• Functions that require a graphics state userobject parameter can use the constant 
NXNullObject to refer to the current graphics state. NXNullObject is declared in 

appkit/Application.h. 

• Functions that pass an array as a parameter include an additional parameter indicating 
the size of the array. The size parameter is used only by pswrap and is not sent to the 
Window Server. It’s your responsibility to provide enough space for the array’s data. 

If a function listed here is set up inconveniently for your purposes, you can always use 
pswrap to make your own. 

Warning: Those functions marked “/* Internal */” below are reserved for use by the Application Kit. 
Only call them in applications that don’t make use of the Kit. 


Effect 

Puts a single value of the specified type on the operand stack 


Gets a single value of the specified type from the operand stack 


Puts a series of objects on the operand stack 


Gets a series of objects from the operand stack 
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void PSadjustcursor(float dx, float dy) 
void PSalphaimage(void) 

void PSbasetocurrent(float x, float y, float *px, float *py) 
void PSbasetoscreen(float x, float y, float *px, float *py) 
void PSbuttondown(boolean *pflag ) 
void PScleartrackingrect(int trectNum, userobject gstate ) 

void PScomposite(float x, float y, float width, float height, userobject srcGstate, float dest x , 
float desty, int op) 

op values: 

NX_CLEAR 

NX_COPY 

NX_SOVER 

NX_DOVER 

NX_SIN 

NX_DIN 

NX_SOUT 

NX_DOUT 

NX_SATOP 

NX_DATOP 

NX_XOR 

NX_PLUSD 

NX_PLUSL 

void PScompositerect(float dest x , float desty, float width, float height, int op) 

op values: PScompositerectO supports NX_HIGHLIGHT in addition to the values 
listed under PScomposite(). 

void PScountframebuffers(int *pcount) 

void PScountscreenlist(int context, int *pcount) 

void PScountwindowlist(int context, int *pcount) 

void PScurrentactiveapp(int *pcontext) /* Internal */ 

void PScurrentalpha(float *pcoverage) 

void PScurrentdefaultdepthlimit(int *plimit) 

void PScurrentdeviceinfo(userobject window, int *pminbps, int *pmaxbps, int *pcolor) 
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void PScurrenteventmask(userobject window, int *pmask ) /* Internal */ 
void PScurrentmouse(userobject window, float *px, float *py) /* Internal */ 
void PScurrentowner(userobject window, int *pcontext) 

void PScurrentrusage(float *pnow, float *puTime, float *psTime, int *pmsgSend, 
int *pmsgRcv, int *pnSignals, int *pnVCSw, int *pnIvCSw) 

void PScurrenttobase(float x, float y, float *px, float *py) 

void PScurrenttoscreen(float x, float y, float *px, float *py) 

void PScurrentuser(int *puid, int *pgid) 

void PScurrentwaitcursorenabled(boolean *pflag) 

void PScurrentwindow(int *pnum) 

void PScurrentwindowalpha(userobject window, int *palpha) 

void PScurrentwindowbounds(userobject window, float *px, float *py, float *pwidth, 
float *pheight ) 

void PScurrentwindowdepth(userobject window, int *pdepth) 
void PScurrentwindowdepth(userobject window, int *plimit ) 
void PScurrentwindowdict(userobject window) /* Internal */ 
void PScurrentwindowlevel(userobject window, int *plevel) 
void PScurrentwriteblock(int *pflag) 

void PSdissolve(float src x , float src y float width, float height, userobject srcGstate, 
float dest x , float desty, float delta ) 

void PSdumpuserobjects(void) 

void PSdumpwindow(int level, userobject window ) /* Internal */ 

void PSdumpwindows(int level, userobject context ) /* Internal */ 

void PSfindwindow(float x, float y, int place, userobject otherWin, float *px, float *py, 
int *pwinFound, boolean *pdidFind) 

place values: 

NX_ ABOVE 
NX BELOW 
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void PSflushgraphics(void) 

void PSframebuffer(int index , int nameLen, char name[], int *pslot, int *punit, 
int *pROMid, int *px, int *py, int *pw, int *ph, int *pdepth) 

void PSfrontwindow(int *pnum) /* Internal */ 

void PShidecursor(void) 

void PShideinstance(float x, float y, float width, float height ) 

void PSmachportdevice(int w, int h, int bbox[], int bboxSize, float matrix[], char *phost, 
char *pport, char *ppixelDict) 

void PSmovewindow(float x, float y, userobject window ) /* Internal */ 

void PSnewinstance(void) 

void PSnextrelease(int size, char stringU) 

/* size is the maximum number of characters copied into string */ 

void PSobscurecursor(void) 

void PSorderwindow(int place, userobject otherWindow, int window ) /* Internal */ 

place values: 

NX_ABOVE 

NX_BELOW 

NX_OUT 

void PSosname(int size, char stringU ) 

/* size is the maximum number of characters copied into string */ 

void PSostype(int *ptype) 

void PSpIacewindow(float x, float y, float width, float height, userobject window) 

/* Internal */ 

void PSplaysound(char *name, int priority ) 

void PSposteventbycontext(int type, float x, float y, int time, int flags, int window, int 
subtype, int datal, int data2, int context, boolean *psuccess ) 

void PSreadimage(void) 

void PSrevealcursor(void) 

void PSrightbuttondown(int *pflag) 
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void PSrightstilldown(int eventnum, boolean *pflag) 
void PSscreenlist(int context, int count, int window s[]) 
void PSscreentobase(float x, float y, float *px, float *py) 
void PSscreentocurrent(float x, float y, float *px, float *py) 
void PSsetactiveapp(int context ) /* Internal */ 
void PSsetalpha(float coverage ) 
void PSsetautofill(boolean flag, userobject window) 
void PSsetcursor(float x, float y, float mx, float my) 


void PSsetdefaultdepthlimit(int limit) 

void PSseteventmask(int mask, userobject window) /* Internal */ 
mask values: 


NX_LMOUSEDOWNMASK 
NX_LMOUSEUPMASK 
NX_RMOUSEDOWNM ASK 
NX_RMOUSEUPM ASK 
NX_MOU SEMOVEDMASK 
NX_LMOUSEDR AGGEDM ASK 
NX_RMOU SEDRAGGEDM ASK 
NX_MOU SEENTEREDMASK 
NX_MOUSEEXITEDM AS K 
NX_KEYDOWNMASK 
NX_KEYUPMASK 
NX_FLAGSCHANGEDMASK 
NX_KITDEFINEDM AS K 
NX_APPDEFINEDMASK 
NX_S Y SDEFINEDMASK 


void PSsetexposurecolor(void) 

void PSsetflushexposures(boolean flag) 

void PSsetinstance(boolean flag) 

void PSsetmouse(float x, float y) 

void PSsetowner(userobject owner, userobject window) 

void PSsetpattern(userobject patternDict) 
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void PSsetsendexposed(boolean flag, userobject window ) /* Internal */ 

void PSsettrackingrect(float x, float _y, float width, float height, boolean leftFlag, 
boolean rightFlag , boolean inside, int userData, int trectNum, userobject gstate ) 

void PSsetwaitcursorenabled(boolean 

void PSsetwindowdepthlimit(int limit, userobject window ) 

void PSsetwindowdict(userobject window) /* Internal */ 

void PSsetwindowlevel(int level, userobject window) 

void PSsetwindowtype(int type, userobject window) 

void PSsetwriteblock(int flag) 

void PSshowcursor(void) 

void PSsizeimage(float x, float y, float width, float height, int *pwidth, int *pheight, 
int *pbitsPerComponent, float matrix[], boolean *pmultiproc, int *pnColors) 

void PSstilldown(int eventnum, boolean *pflag) 

void PStermwindow(userobject window) /* Internal */ 

void PSwindow(float x, float y, float width, float height, int type, int *pwindow) 

/* Internal */ 

void PSwindowdevice(userobject window) 

void PSwmdowdeviceround(userobject window) 

void PSwindowlist(int context, int count, int windows[]) 
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Run-Time Functions 


This section describes functions and macros that are part of NeXT’s run-time system for the 
Objective-C language. Some, such as sel_getUid() and objc_loadModules(), might be 
useful when called within an Objective-C program, but most are provided mainly to make 
it possible to define other interfaces to the run-time system. For most programs, 
Objective-C is itself a sufficient and complete interface to the run-time system; the 
messages and class definitions in Objective-C source files are compiled to execute correctly 
at run time without the aid of additional function calls. 

The functions described here are divided into five groups, each with its own prefix: 

• The basic run-time functions have an “objc_” prefix. 

• Functions that operate on class objects have a “class_” prefix and take as their first 
argument a structure of type Class. Class is the defined type (in objc/objc.h) for class 
objects. However, to receive messages in Objective-C source code, class objects must 
be of type id, so id rather than Class is the type generally used in Objective-C 
programs. 

• Functions that operate on instances have an “object_” prefix and take as their first 
argument the id of the instance. 

• Functions that give information about method selectors have a “sel_” prefix. 

• Functions that describe method implementations have a “method_” prefix. 

NeXT reserves these prefixes for functions in the run-time system. 

In addition to these functions, there are also a few macros that operate on the values passed 
in a message. They begin with a “marg_” prefix (for “message argument”). 


class_addClassMethods() —> See class_getInstanceMethod() 
class_addInstanceMethods() —> See class_getInstanceMethod() 
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class_createlnstance(), classcreatelnstanceFromZoneO 

SUMMARY Create a new instance of a class 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

id class_createInstance(Class aClass, unsigned int indexedlvarBytes) 
id class_createInstanceFromZone(Class aClass, unsigned int indexedlvarBytes, 
NXZone *zone) 

DESCRIPTION 

These functions provide an interface to the object allocators used by the run-time 
system. The default allocators, which can be changed by reassigning the _alloc and 
_zone Alloc variables, create a new instance of aClass, initialize its isa instance variable 
to point to the class, and return the new instance. All other instance variables are 
initialized to 0. 

The two functions are identical, except that class_createInstanceFromZone() 
allocates memory for the new object from the region specified by zone', 
class_createlnstance() doesn’t specify a zone. Object’s new method uses 
class_createlnstance() to allocate memory for a new object. The alloc and 
allocFromZone: methods use class_createInstanceFromZone(), with alloc taking 
the memory from the default zone returned by NXDeaultMallocZone(). 

The second argument to both functions, indexedlvarBytes, states the number of extra 
bytes required for indexed instance variables. Normally, it’s 0. 

Indexed instance variables are instance variables that don’t have a fixed size; usually 
they’re arrays whose length can’t be computed at compile time. Since the components 
of a C structure can’t be of uncertain size, indexed instance variables can’t be declared 
in the class interface. The class must account for them outside the normal channels 
provided by the Objective-C language. 


class_createlnstance() 


3-149 



All of the storage required for indexed instance variables must be allocated through this 
function. The following code shows how it might be used in an instance-creating class 
method: 

+ new:(unsigned int)numBytes 
{ 

self = class_createlnstance((Class)self, numBytes); 
length = numBytes; 


} 

- (char *)getArray 
{ 

return(object_getIndexedlvars(self) ) ; 

} 

Indexed instance variables should be avoided if at all possible. It’s a much better 
practice to store variable-length data outside the object and declare one real instance 
variable that points to it and perhaps another that records its length. For example: 

+ new: (unsigned int)numBytes 
{ 

self = [super new]; 
data = malloc(numBytes); 
length = numBytes; 

} 

- (char *)getArray 
{ 

return data; 

} 

RETURN 

Both functions return a new instance of aClass. 


class_createInstanceFromZone() -a See class_createlnstance() 
class_getClassMethod() -»See classgetlnstanceMethodQ 
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class_getInstanceMethod(), class_getClassMethod(), 
class_addInstanceMethods(), class_addClassMethods(), 
class_removeMethods() 

SUMMARY Get, add, and remove methods for the class 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

Method class_getInstanceMethod(Class aClass, SEL aSelector ) 

Method class_getClassMethod(Class aClass, SEL aSelector ) 
void class_addInstanceMethods(Class aClass , struct objc_method_list * methodList) 
void c!ass_addClassMethods(Class aClass, struct objc_method_list *methodList) 
void class_removeMethods(Class aClass, struct objc_method_list ^methodList) 

DESCRIPTION 

The first two functions, class_getInstanceMethod() and class_getClassMethod(), 
return a pointer to the class data structure that describes the aSelector method. For 
class_getInstanceMethod(), aSelector must identify an instance method; for 
cIass_getClassMethod(), it must identify a class method. Both functions return a 
NULL pointer if aSelector doesn’t identify a method defined in or inherited by aClass. 

The run-time system uses the next two functions, class_addInstanceMethods() and 
c!ass_addClassMethods(), to implement Objective-C categories. Each function adds 
the methods in methodList to the dictionary of methods defined for aClass. 
class_addInstanceMethods() adds methods that can be used by instances of the class 
and class_addClassMethods() adds methods used by the class object. Before adding 
a method, both functions map the method name to a SEL selector and check for 
duplicates. A warning is sent to the standard error stream if any ambiguities exist. 

The last function, class_removeMethods(), removes the methods in methodList from 
aClass. It can remove both class and instance methods. 

RETURN 

class_getInstanceMethod() and class_getClassMethod() return a pointer to the data 
structure that describes the aSelector method as implemented for aClass. 
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class_getInstanceVariable() 


SUMMARY Get the class template for an instance variable 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

Ivar dass_getInstanceVariabIe(Class aClass, STR variableName ) 

RETURN 

This function returns a pointer to the class data structure that describes the 
variableName instance variable. If aClass doesn’t define or inherit the instance 
variable, a NULL pointer is returned. 


class_getVersion() —> See class_setVersion() 


class_poseAs() 

SUMMARY Pose as the superclass 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

Class class_poseAs(Class thelmposter, Class theSuperclass ) 

DESCRIPTION 

class_poseAs() causes one class, thelmposter , to take the place of its own superclass, 
theSuperclass. Messages sent to theSuperclass will actually be received by 
thelmposter. The posing class can’t declare any new instance variables, but it can 
define new methods and even override methods defined in the superclass. 

Posing is usually done through Object’s poseAs: method, which calls this function. 
RETURN 

class_poseAs() returns its first argument, thelmposter. 
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class_removeMethods() —> See class_getInstanceMethod() 


class_setVersion(), class_getVersion() 

SUMMARY Set and get the class version 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

void class_setVersion(Class aClass, int theVersion ) 
int class_getVersion(Class aClass) 

DESCRIPTION 

These functions set and return the class version number. This number is used when 
archiving instances of the class. 

Object’s setVersion: and version methods do the same work as these functions. 
RETURN 

class_getVersion() returns the version number for aClass last set by 
classset Yersion(). 


marg getRefO -a See marg_getValue() 
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marg_getValue(), marg_getRef(), margsetValueQ 

SUMMARY Examine and alter method argument values 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

type-name marg_getValue(marg_list argFrame, int offset, type-name ) 

type-name *marg_getRef(marg_list argFrame, int offset, type-name) 

void marg_setValue(marg_list argFrame, int offset, type-name, type-name value ) 

DESCRIPTION 

These three macros get and set the values of arguments passed in a message. They’re 
designed to be used within implementations of the forward:: method, which is 
described under the Object class in Chapter 2, “Class Specifications.” 

The first argument to each macro, argFrame, is a pointer to the list of arguments passed 
in the message. The run-time system passes this pointer to the forward:: method, 
making it available to be used in these macros. The next two arguments—an offset into 
the argument list and the type of the argument at that offset—can be obtained by calling 

method_getArgumentInfo() 

The first macro, marg getValue, returns the argument at offset in argFrame. The 
return value, like the argument, is of type type-name. The second macro, 
marg getRef, returns a reference to the argument at offset in argFrame. The pointer 
returned is to an argument of the type-name type. The third macro, marg_setValue, 
alters the argument at offset in argFrame by assigning it value. The new value must be 
of the same type as the argument. 

Since method_getArgumentInfo() encodes the argument type according to the 
conventions of the @encode() compiler directive, the type must first be expanded to a 
full type name before it can be used in these macros. The offset provided by 
method_getArgumentInfo() can be passed directly to the macros without change. 

RETURN 

marg_getValue returns a type-name argument value. marg_getRef returns a pointer 
to a type-name argument value. 


margjsetValueO —> See marg_getValue() 

method_getArgumentInfo() See method j*etNumberOfArguments() 
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method_getNumberOfArguments(), method_getSizeOfArguments(), 
method_getArgumentInfo() 

SUMMARY Get information about a method 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-class.h> 

unsigned int method_getNumberOfArguments(Method aMethod) 
unsigned int method_getSizeOfArguments(Method aMethod) 
unsigned int method_getArgumentInfo(Method aMethod, int index, char **type, 
int *offset ) 

DESCRIPTION 

The three functions described here all provide information about the argument structure 
of a particular method. They take as their first argument the method’s data structure, 
aMethod, which can be obtained by calling class_getInstanceMethod() or 
class_getClassMethod(). 

The first function, method_getNumberOfArguments(), returns the number of 
arguments that aMethod takes. This will be at least two, since it includes the “hidden” 
arguments, self and _cmd, which are the first two arguments passed to every method 
implementation. 

The second function, method_getSizeOfArguments!), returns the number of bytes 
that all of aMethod 1 s arguments, taken together, would occupy on the stack. This 
information is required by objc_msgSendv(). 

The third function, method_getArgumentInfo(), takes an index into aMethod' s 
argument list and returns, by reference, the type of the argument and the offset to the 
location of that argument in the list. Indices begin with 0. The “hidden” arguments self 
and _cmd are indexed at 0 and 1; method-specific arguments begin at index 2. The 
offset is measured in bytes and depends on the size of arguments preceding the indexed 
argument in the argument list. The type is encoded according to the conventions of the 
@encode() compiler directive. 

The information obtained from method_getArgumentInfo() can be used in the 
marg getValue, marg_getRef, and marg_setValue macros to examine and alter the 
values of an argument on the stack after aMethod has been called. The offset can be 
passed directly to these macros, but the type must first be decoded to a full type name. 

RETURN 

method_getNumber Of Arguments!) returns how many arguments the 
implementation of aMethod takes, and method_getSizeOfArguments() returns how 
many bytes the arguments take up on the stack. method_getArgumentInfo() returns 
the index it is passed. 
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method_getSizeOfArguments() —» See method_getNumberOfArguments() 
objcaddClassQ —> See objc_getClass() 


objc_getClass(), objc_getMetaClass(), objc_getClasses(), objc_addClass(), 
objc_getModules() 

SUMMARY Manage run-time structures 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-runtime.h> 

id objc_getClass(STR aClassName) 
id objc_getMetaClass(STR aClassName) 

NXHashTable *objc_getClasses(void) 
void objc_addClass(Class aClass) 

Module *objc_getModules(void) 

DESCRIPTION 

These functions return and modify the principal data structures used by the run-time 
system. 

objc_getClass() returns the id of the class object for the aClassName class, and 
objc_getMetaClass() returns the id of the metaclass object for the aClassName class. 
The metaclass object holds information used by the class object, just as the class object 
holds information used by instances of the class. Both functions print a message to the 
standard error stream if aClassName isn’t part of the executable image. 

objc_getClasses() returns a pointer to a hash table containing all the Objective-C 
v classes that are currently part of the executable image. The NXHashTable return type 
is defined in the objc/hashtable.h header file. objc_addClass() adds aClass to the list 
of currently loaded classes. 

The compiler creates a Module data structure for each file it compiles. The 
objc_getModules() function returns a pointer to a list of all the modules that are part 
of the executable image. 

RETURN 

objc_getClass() and objc_getMetaClass() return the class and metaclass objects for 
aClassName. objcjgetClasses () returns a pointer to a hash table of all current classes, 
and objc_getModules() returns a pointer to all current modules. 
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objc_getClasses() —> See objc_getClass() 
objc_getMetaClass() —> See objc_getClass() 
objc_getModuIes() —> See objc_getClass() 


objc_loadModules(), objc_unloadModules() 

SUMMARY Dynamically load and unload classes 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-load.h> 

long objc_IoadModules(char * files]}, NXStream * stream, 

void ( *callback)(C\ass , Category), struct mach_header **hea.der , 
char *debugFilename ) 

long objc_un!oadModules(NXStream * stream, void {^callback)] Class, Category)) 
DESCRIPTION 

objc_IoadModules() dynamically loads object files containing Objective-C class and 
category definitions into a running program. Its first argument, files, is a list of 
null-terminated pathnames for the object files containing the classes and categories that 
are to be loaded. They can be full paths or paths relative to the current working 
directory. The second argument, stream, is a pointer to an NXStream where any error 
messages produced by the loader will be written. It can be NULL, in which case no 
messages will be written. 

The third argument, callback, allows you to specify a function that will be called 
immediately after each class or category is loaded. When a category is loaded, the 
function is passed both the Category structure and the Class structure for that category. 
When a class is loaded, it’s passed only the Class structure. Like stream , callback can 
be NULL. 

The fourth argument, header, is used to get a pointer to the mach_header structure for 
the loaded modules. It, too, can be NULL. All the modules in files are grouped under 
the same header. 

The final argument, which also can be NULL, is the pathname for a file that the loader 
will create and initialize with a copy of the loaded modules. This file can be passed to 
the debugger and added to the executable image that it’s debugging. For example: 

(gdb) add-file debugFilename 
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obj junloadModules() unloads all the modules loaded by objc_loadModules(), that 
is, all the modules from the files list. Each time it’s called, it unloads another set of 
modules, working its way back from the modules loaded by the most recent call to 
objc_loadModules() to those loaded by the next most recent call, and so on. 

The first argument to obj_unloadModules(), stream, is a pointer to an NXStream 
where error messages will be written. Its second argument, callback, allows you to 
specify a function that will be called immediately before each class or category is 
unloaded. Both arguments can be NULL. 

RETURN 

Both functions return 0 if the modules are successfully loaded or unloaded and 1 if 
they’re not. 


objc msgSendQ, objc_msgSendSuper(), objc_msgSendv() 

SUMMARY Dispatch messages at run time 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-runtime.h> 

id objc_msgSend(id theReceiver, SEL theSelector ,...) 
id objc_msgSendSuper(struct objc_super *superContext, SEL theSelector ,...) 
id objc_msgSendv(id theReceiver, SEL theSelector, unsigned int argSize, 
marg_list argFrame) 

DESCRIPTION 

The compiler converts every message expression into a call on one of the first two of 
these three functions. Messages to super are converted to calls on 
objc_msgSendSuper(); all others are converted to calls on objc_msgSend(). 

Both functions find the implementation of the theSelector method that’s appropriate for 
the receiver of the message. For objc_msgSend(), theReceiver is passed explicitly as 
an argument. For objc_msgSendSuper(), superContext defines the context in which 
the message was sent, including who the receiver is. 

Arguments that are included in the aSelector message are passed directly as additional 
arguments to both functions. 

Calls to objc_msgSend() and objc_msgSendSuper() should be generated only by the 
compiler. You shouldn’t call them directly in the Objective-C code you write. 
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The third function, objc_msgSendv(), is an alternative to objc_msgSend() that’s 
designed to be used within class-specific implementations of the forward:: method. 
Instead of being passed each of the arguments to the aSelector message, it takes a 
pointer to the arguments list, argFrame, and the size of the list in bytes, argSize. 
argSize can be obtained by calling method_getArgumentSize(); argFrame is passed 
as the second argument to the forward:: method. 

objc_msgSendv() parses the argument list based on information stored for aSelector 
and the class of the receiver. Because of this additional work, it’s more expensive than 
objc_msgSend(). 

RETURN 

Each method passes on the value returned by the aSelector method. 


objc_msgSendSuper() —» See objc_msgSend() 
objc_msgSendv() —> See objc_msgSend() 
objc_unloadModules() -» See objcloadModulesO 
objectcopyO -a See object_dispose() 
object_copyFromZone() —> See objectdisposeO 


objectdisposeO, object copyO, object_realloc(), objectcopyFromZoneO, 
object_reaIlocFromZone() 

SUMMARY Manage object memory 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/Object.h> 

id object_dispose(Object *anObject) 

id object_copy(Object *anObject, unsigned int indexedlvarBytes ) 
id object_realloc(Object *anObject, unsigned int numBytes) 
id object_copyFromZone(Object *anObject, unsigned int indexedlvarBytes, 
NXZone *zone) 

id object_reaHocFromZone(Object *anObject, unsigned int numBytes, 
NXZone *zone) 
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DESCRIPTION 

These five functions, along with class_createlnstance() and 
class_createInstanceFromZone(), manage the dynamic allocation of memory for 
objects. Like those two functions, each of them is simply a “cover” for—a way of 
calling—another, private function. 

object_dispose() frees the memory occupied by anObject after setting its isa instance 
variable to nil, and returns nil. The function it calls to do this work can be changed by 
reassigning the _dealloc variable. 

object_copy() and object_copyFromZone() create a new object that’s an exact copy 
of anObject and return the new object. The second argument to both functions, 
indexedlvarBytes, specifies the number of additional bytes that should be allocated for 
the copy to accommodate indexed instance variables; it serves the same purpose as the 
second argument to class_createlnstance(). The functions that object_copy() and 
object_copyFromZone() call to do this work can be changed by reassigning the _copy 
and _zoneCopy variables. 

object_realloc() and object_reallocFromZone() reallocate storage for anObject , 
adding numBytes if possible. The memory previously occupied by anObject is freed if 
it can’t be reused, and a pointer to the new location of anObject is returned. The 
functions that objectreallocQ and object_reaIIocFromZone() call to do this work 
can be changed by reassigning the _realloc and _zoneRealloc variables. 

The Object class defines a method interface for the first three of these functions. The 
free instance method corresponds to object_dispose(). And the copy and 
copyFromZone: methods correspond to object_copy() and object_copyFromZone(). 

RETURN 

object_dispose() returns nil, object_copy() and object_copyFromZone() return the 
copy, and object_realloc() and object_reallocFromZone() return the reallocated 
object. 
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object_getClassName() 


SUMMARY Return the class name 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc.h> 

STR object_getClassName(id anObject ) 

DESCRIPTION 

This function returns the name of anObject ’s class. anObject should be an instance 
object, not a class object. 

objectgetlndexedlvarsO 

SUMMARY Return a pointer to an object’s extra memory 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc.h> 

void *object_getIndexedIvars(id anObject) 

RETURN 

object_getIndexedIvars() returns a pointer to the first indexed instance variable of 
anObject, or NULL if anObject has no indexed instance variables. 

SEE ALSO 

class_createlnstance() 

object_getInstanceVariable() -A See object_setInstanceVariable() 
object_realloc() -> See object_dispose() 
object_reallocFromZone() —> See object_dispose() 
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object_setInstanceVariable(), object_getInstanceVariable() 

SUMMARY Set and get instance variables 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/Object.h> 

Ivar object_setInstanceVariable(id anObject, STR variableName, void *value ) 

Ivar object_getInstanceVariab!e(id anObject, STR variableName, void **valuePtr) 

DESCRIPTION 

object_setInstanceVariable() assigns a new value to the variableName instance 
variable belonging to anObject. The new value is passed in the third argument, value . 
object_getInstanceVariable() gets the value of anObject’s variableName instance 
variable. The value is returned by reference through the third argument, valuePtr. 

These functions provide a way of setting and getting instance variables, without having 
to implement methods for that purpose. For example. Interface Builder calls 
object_setInstanceVariable() to initialize programmer-defined “outlet” instance 
variables. 

RETURN 

Both functions return a pointer to the class template that describes the variableName 
instance variable. A NULL pointer is returned if anObject has no instance variable 
with that name. 

The returned template has a field describing the data type of the instance variable. You 
can check it to be sure that the value set is of the correct type. 


sel_getName() -> See sel_getUid() 
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sel_getUid(), selgetNameQ 


SUMMARY Match method selectors with method names 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc.h> 

SEL seI_getUid(STR aName) 

STR sel_getName(SEL aSelector ) 

DESCRIPTION 

The first function, sel_getUid(), returns the unsigned integer that’s used at run time to 
identify the aName method. Whenever possible, you should use the @selector() 
directive to ask the compiler, rather than the run-time system, to provide the selector 
for a method. This function should be used only if the name isn’t known at compile 
time. 

The second function, sel_getName(), is the inverse of the first. It returns the name that 
was mapped to aSelector. 

RETURN 

seI_getUid() returns the selector for the aName method, or 0 if there is no known 
method with that name. sel_getName() returns a character string with the name of the 
method identified by the aSelector selector. If aSelector isn’t a valid selector, a NULL 
pointer is returned. 
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seI_isMapped() 

SUMMARY Determine whether a selector is valid 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc.h> 

BOOL seI_isMapped(SEL aSelector) 

RETURN 

sel_isMapped() returns YES if aSelector is a valid selector (is currently mapped to a 
method implementation) or could possibly be one (because it lies within the same range 
as valid selectors); otherwise it returns NO. 

Because all of a program’s selectors are guaranteed to be mapped at start-up, this 
function has little real use. It’s included here for reasons of backward compatibility 
only. 


al!oc(), _dealIoc(), _realIoc(), _copy(), _zoneAIIoc(), _zoneRea!loc(), 
zoneCopyO, _error() 

SUMMARY Set functions used by the run-time system 

LIBRARY libsys_s.a 

SYNOPSIS 

#import <objc/objc-runtime.h> 

id (*_alloc)(Class aClass, unsigned int indexedlvarBytes ) 
id (*_dealloc)(Object *anObject ) 
id (*_realloc)(Object *anObject, unsigned int numBytes) 
id (*_copy)(Object *anObject, unsigned int indexedlvarBytes ) 
id (*_zoneAlloc)(Class aClass, unsigned int indexedlvarBytes , NXZone *zone) 
id (*_zoneRealloc)(Object *anObject, unsigned int numBytes , NXZone *zone) 
id (*_zoneCopy)(Object *anObject, unsigned int indexedlvarBytes , NXZone *zone) 
void (*_error)(Object *anObject, char *format, va_list ap) 
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DESCRIPTION 


These variables point to the functions that the run-time system uses to manage memory 
and handle errors. By reassigning a variable, a function can be replaced with another 
of the same type. The example below shows a temporary reassignment of the 
_zoneAlloc function: 

id (*theFunction)(); 
theFunction = _zoneAlloc; 

_zoneAlloc = someOtherFunction; 

/* 

* code that calls the class_createInstanceFromZone() function, 

* or sends alloc and allocFromZone: messages, goes here 

*/ 

zoneAlloc = theFunction; 


_alloc points to the function, called through class_createlnstance(), used to 
allocate memory for new instances, and _zoneAlloc points to the function, called 
through class_createInstanceFromZone(), used to allocate the memory for a new 
instance from a specified zone. 

_dealloc points to the function, called through object_dispose(), used to free 
instances. 

jrealloc points to the function, called through object_realloc(), used to reallocate 
memory for an object, and _zoneRealloc points to the function, called through 
object_reallocFromZone(), used to reallocate memory from a specified zone. 

_copy points to the function, called through object_copy(), used to create an exact 
copy of an object, and _zoneCopy points to the function, called through 
object_copyFromZone(), used to create the copy from memory in the specified 
zone. 

_error points to the function that the run-time system calls in response to an error. 
By default, it prints formatted error messages to the standard error stream and calls 
abortQ to produce a core file. 


copy -> See alloc 
dealloc See alloc 
error -» See alloc 
realloc —> See alloc 
zoneAlloc —> See alloc 
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zoneCopy —> See alloc 
zoneRealloc —> See alloc 
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Chapter 4 

PostScript Operators 


This chapter contains detailed descriptions of NeXT’s extensions to the Display PostScript 
system. It also lists the standard PostScript operators that have different or additional 
effects in the NeXT implementation. For information on the standard PostScript language 
operators, see the PostScript Language Reference Manual See the Extensions for the 
Display PostScript System manual for details on the operators Adobe Systems Incorporated 
added for the Display PostScript system. Information on these and other references for the 
PostScript language is listed in “Suggested Reacting” in the NeXT Technical Summaries 
manual. 

The operators marked “internal” shouldn’t be used in applications based on the Application 
Kit since your use of them will conflict with the Kit’s. 

This chapter presents the operators in alphabetical order and uses the same format as that 
of the operator descriptions in the PostScript Language Reference Manual. The Technical 
Summaries manual provides a complete summary of all PostScript operators, organized 
into groups of related operators. Chapter 3, “C Functions,” describes the C interface to the 
operators listed in this chapter. 


adjustcursor dxdy adjustcursor - 

Moves the cursor location by {dx, dy) from its current location, dx and dy are given 
in the current coordinate system. If the current device isn’t a window, the invalidid 
error is executed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

currentmouse, setmouse 


alphaimage pixelswide pixelshigh bits/sample matrix procg [... procj multiproc ncolors 

alphaimage - 

Renders an image whose samples each contain one, three, or four color 
components plus an alpha component. (Most programmers should use 
NXImageBitmapO instead of alphaimage.) 
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banddevice 


This operator is modeled on the colorimage operator as described in PostScript 
Language Color Extensions (see “Suggested Reading” in the NeXT Technical 
Summaries manual). It differs from colorimage in that it assumes an alpha 
component in addition to the color components for each sample. 

The sampled image is a rectangular array of pixelswide*pixelshigh pixels. For each 
pixel, there must be ncolors color components and one alpha component. The only 
valid possibilities for ncolors are 1 (gray scale), 3 (RGB), and 4 (CMYK). Each 
color and alpha component is represented by bits!sample bits. Each color 
component is premultiplied; that is, it’s the result of the prior multiplication of the 
color contribution and the corresponding alpha value. (See “Premultiplication” in 
the Concepts manual for more information.) 

alphaimage calls its procedure operand(s) repeatedly to get the color and alpha 
values to be rendered. See PostScript Language Color Extensions for a discussion 
of the data formats that these procedures must return. 

multiproc is a boolean value referring to whether the color and alpha components 
are each supplied separately ( multiproc is true) or interleaved {multiproc is false). 
In the single-procedure form {multiproc is false), the samples are GA (the gray and 
alpha components), RGBA (RGB components plus an alpha component), or 
CMYKA (CMYK components plus an alpha component). In the 
multiple-procedure form {multiproc is true), the alpha procedure is last 
{proc ncolors)’ f° r example, for ncolors= 1 , this operator has the form: 

pixelswide pixelshigh bits!sample matrix dataproc alphaproc true 1 

alphaimage - 

ERRORS 

invalidid, limitcheck, rangecheck, stackunderflow, typecheck, undefined, 
undefinedresult 


matrix width height proc banddevice - % undefined 

This standard PostScript operator is not defined in the NeXT implementation of the 
Display PostScript system. 
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basetocurrent 


xy basetocurrent x'y' 


basetoscreen 


buttondown 


Converts ( x , y) from the current window’s base coordinate system to its current 
coordinate system. If the current device isn’t a window, the invalidid error is 
executed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

basetoscreen, currenttobase, currenttoscreen, screentobase, 
screentocurrent 


xy basetoscreen x'y' 

Converts (x, y) from the current window’s base coordinate system to the screen 
coordinate system. If the current device isn’t a window, the invalidid error is 
executed. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

basetocurrent, currenttobase, currenttoscreen, screentobase, 
screentocurrent 


- buttondown bool 

Returns true if the left or only mouse button is currently down; otherwise it returns 
false. 

Note: To test whether the mouse button is still down from a mouse-down event, 
use stilldown instead of buttondown; buttondown will return true even if the 
mouse button has been released and pressed again since the original mouse-down 
event. 

ERRORS 

none 

SEE ALSO 

currentmouse, rightbuttondown, rightstilldown, stilldown 


basetocurrent 
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cleardictstack 


cleartrackingrect 


- cleardictstack - 

Returns the dictionary stack to its initial state, in which it contains only systemdict, 
shareddict, and userdict. cleardictstack should be used instead of counting the 
number of dictionaries to pop off—that is, instead of 


{ countdictstack 2 ge { exit } end } loop 

Note: Adobe has recently added this operator to the Display PostScript system. 
This entry will be removed when cleardictstack is documented in Adobe’s 
manuals. 

ERRORS 

dictstackunderflow 


trectnum gstate cleartrackingrect - 

Clears the tracking rectangle with the number trectnum, as set by settrackingrect, 
in the device referred to by gstate. If no such rectangle exists, the invalidid error 
is executed. If gstate is null, the current graphics state is assumed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

settrackingrect 
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composite src x src y width height srcgstate dest x dest y op composite - 

Performs the compositing operation specified by op between pairs of pixels in two 
images, a source and a destination. The source pixels are in the window device 
referred to by the srcgstate graphics state, and the destination pixels are in the 
current window. If srcgstate is null, the current graphics state is assumed. (If 
srcgstate or the current graphics state doesn’t refer to a window device, the 
invalidid error is executed.) The remaining operands define the shape that contains 
the source and destination pixels and the locations of that shape in the current 
coordinate system of the respective graphics states. The result of an operation on 
a source and destination pixel replaces the destination pixel. 

The rectangle specified by src x , src^ width, and height defines the source image. 
The outline of the rectangle may cross pixel boundaries due to fractional 
coordinates, scaling, or rotated axes. The pixels included in the source are all those 
that the outline of the rectangle encloses or enters; for more information, see the 
general rule given in the Concepts manual, under “Imaging Conventions.” 

There’s one destination pixel for each pixel in the source. The source and 
destination images have the same size, shape, and orientation. (Even if the axes 
have a different orientation in the source and destination graphics states, the images 
will not; composite will not rotate images.) In screen coordinates, the difference 
between src x and dest x —both truncated float values—is the x displacement 
between all source and destination pixels; src y and dest y similarly determine the y 
displacement. 

The source image is clipped to the frame rectangle of the window in the source 
graphics state, and the destination image is clipped to the frame rectangle and 
clipping path of the window in the current graphics state. 

op specifies the compositing operation. The choices for op and the result of each 
operation are given in Figure 4-1 on the following page. For a detailed explanation 
of each operator, see “Types of Compositing Operations” in the Concepts manual. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

compositerect, setalpha, setgray, sethsbcolor, setrgbcolor 
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Destination 

Source before 

opaque 

transparent transparent 

Operation Destination after 

Source image. 


Transparent. 


Sum of source and destination images, with color values approaching 0 as a limit. 

Sum of source and destination images, with color values approaching 1 as a limit. 
(PlusL is not implemented for the Megapixel Display.) 

Source image wherever source image is opaque, and destination image elsewhere. 


Destination image wherever destination image is opaque, and source image elsewhere. 


Source image wherever both images are opaque, and transparent elsewhere. 


Destination image wherever both images are opaque, and transparent elsewhere. 

Source image wherever source image is opaque but destination image is transparent, 
and transparent elsewhere. 

Destination image wherever destination image is opaque but source image is transparent, 
and transparent elsewhere. 

Source image wherever both images are opaque, destination image wherever destination 
image is opaque but source image is transparent, and transparent elsewhere. 

Destination image wherever both images are opaque, source image wherever source 
image is opaque but destination image is transparent, and transparent elsewhere. 

Source image wherever source image is opaque but destination image is transparent, 
destination image wherever destination image is opaque but source image is transparent, 
and transparent elsewhere. 

Figure 4-1. Compositing Operations 
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compositerect dest x dest y width height op compositerect - 


copypage 


In general, this operator is the same as the composite operator except that there’s 
no real source image. The destination is in the current graphics state; src x , src y , 
width , and height describe the destination image in that graphics state’s current 
coordinate system. The effect on the destination is as if there were a source image 
filled with the color and coverage specified by the graphics state’s current color 
parameter, op has the same meaning as the op operand of the composite operator; 
however, one additional operation, Highlight, is allowed. 

On the Megapixel Display, Highlight turns every white pixel in the destination 
rectangle to light gray and every light gray pixel to white, regardless of the pixel’s 
coverage value. Repeating the same operation reverses the effect. (Highlight may 
act differently on other devices. For example, on displays that assign just one bit 
per pixel, it would invert every pixel.) 

Note: The Highlight operation doesn’t change the value of a pixel’s coverage 
component. To ensure that the pixel’s color and coverage combination remains 
valid, Highlight operations should be temporary and should be reversed before any 
further compositing. 

For compositerect, the pixels included in the destination are those that the outline 
of the specified rectangle encloses or enters; for more information, see the general 
rule given in the Concepts manual, under “Imaging Conventions.” The destination 
image is clipped to the frame rectangle and clipping path of the window in the 
current graphics state. 

If the current graphics state doesn’t refer to a window device, the invalidid error is 
executed. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

composite, setalpha, setgray, sethsbcolor, setrgbcolor 


- copypage - % different in the NeXT implementation 

This standard PostScript operator has no effect in the NeXT implementation of the 
Display PostScript system. 

ERRORS 

none 

SEE ALSO 

erasepage, showpage 
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countframebuffers 


- countframebuffers count 


countscreenlist 


countwindowlist 


Returns the number of frame buffers that the Window Server is actually using. 

ERRORS 

stackoverflow 


SEE ALSO 
framebuffer 


context countscreenlist count 

Returns the number of windows in the screen list that were created by the 
PostScript context specified by context. This is in contrast with countwindowlist, 
which returns the number of windows created by the context without regard to their 
inclusion in the screen list. 

If context is 0, all windows in the screen list are counted, without regard to the 
context that created them. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

countwindowlist, screenlist, windowlist 


context countwindowlist count 

Returns the number of windows that were created by the PostScript context 
specified by context. This is in contrast with countscreenlist, which returns the 
number of windows in the screen list that were created by the PostScript context 
specified by context. 

If context is 0, all windows are counted, without regard to the context that created 
them. 

ERRORS 

stackunderflow, typecheck 
SEE ALSO 

countscreenlist, screenlist, windowlist 
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currentactiveapp - currentactiveapp context % internal 

Returns the active application’s context. This operator is used by the window 
packages to assist with wait cursor operation. 

ERRORS 

stackoverflow 

SEE ALSO 
setactiveapp 


currentalpha - currentalpha coverage 

Returns the coverage parameter of the current graphics state. 

ERRORS 

none 

SEE ALSO 

composite, setalpha 


currentdefaultdepthlimit 

- currentdefaultdepthlimit depth % internal 

Returns the current context’s default depth limit. This value determines a new 
window’s depth limit. 

ERRORS 

stackoverflow 

SEE ALSO 

setdefaultdepthlimit, setwindowdepthlimit, currentwindowdepthlimit, 
currentwindowdepth 


currentdeviceinfo window currentdeviceinfo min max bool 

Returns device-related information about the current state of window, min and max 
are the smallest and largest number of bits per sample, respectively, and bool is a 
boolean value indicating whether the device is a color device. 

ERRORS 

invalidid, stackunderflow, typecheck 
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currenteventmask 


window currenteventmask mask % internal 


currentmouse 


currentowner 


Returns the current Window Server-level event mask for the specified window. For 
windows created by the Application Kit, this mask may allow additional event 
types beyond those requested by the application. 

Normally you should use the Window object’s eventMask method instead of the 
currenteventmask operator. Use this operator only if you’re bypassing the 
Application Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

seteventmask 


window currentmouse x y % internal 

Returns the current x and y coordinates of the mouse location in the base coordinate 
system of the specified window. If the mouse isn’t inside the specified window, 
these coordinates may be outside the coordinate range defined for the window. If 
window is 0, the current mouse position is returned relative to the screen coordinate 
system. 

Normally you should use the Window object’s getMouseLocation: method 
instead of the currentmouse operator. Use this operator only if you’re bypassing 
the Application Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

basetocurrent, basetoscreen, buttondown, rightbuttondown, 
rightstilldown, setmouse, stilldown 


window currentowner context 

Returns a number identifying the PostScript context that currently owns the 
specified window. By default, this is the PostScript context that created the 
window. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

setowner, termwindow, window 


4-10 


Chapter 4: PostScript Operators 



currentrusage - currentrusage dime utime stime msgsend msgrcv nsignals nvcsw nivcsw 


currenttobase 


currenttoscreen 


Returns information about the current time of day and about resource usage by the 
Window Server, as provided by the UNIX system call getrusage(). The items 
returned, and their types, are as follows: 


Name 

Type 

Value 

ctime 

float 

Current time in seconds, modulo 10000 

utime 

float 

User time for the Server process in seconds 

stime 

float 

System time for the Server process in seconds 

msgsend 

int 

Messages sent by the Server to clients 

msgrcv 

int 

Message received by the Server from clients 

nsignals 

int 

Number of signals received by the Server process 

nvcsw 

int 

Number of voluntary context switches 

nivcsw 

int 

Number of involuntary context switches 


xy currenttobase x'y' 

Converts (. x , y) from the current coordinate system of the current window to its base 
coordinate system. If the current device isn’t a window, the invalidid error is 
executed. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

basetocurrent, basetoscreen, currenttoscreen, screentobase, 
screentocurrent 


xy currenttoscreen x'y' 

Converts (jc, y) from the current coordinate system of the current window to the 
screen coordinate system. If the current device isn’t a window, the invalidid error 
is executed. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

basetocurrent, basetoscreen, currenttobase, screentobase, 
screentocurrent 
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currentuser - currentuser uidgid 

Returns the user id ( uid) and the group id (gid) of the user currently logged in on 
the console of the machine that’s running the Window Server. 

ERRORS 

stackoverflow 


currentwaitcursorenabled 

context currentwaitcursorenabled bool 

Returns the state of context's wait cursor flag. If context is 0, returns the state of 
the global wait cursor flag. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

setwaitcursorenabled 


currentwindow - currentwindow window 

Returns the window number of the current window. Executes the invalidid error 
if the current device isn’t a window. 

ERRORS 

invalidid 

SEE ALSO 

windowdeviceround 


currentwindowalpha window currentwindowalpha state 

Returns an integer indicating whether the Window Server is currently storing alpha 
values for the specified window. Possible state values are: 

-2 Window is opaque; alpha values are explicitly allocated. 

0 Alpha values are stored explicitly. 

2 Window is opaque; no explicit alpha. 

ERRORS 

invalidid, stackunderflow, typecheck 
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currentwindowbounds window currentwindowbounds x y width height 

Returns the location and size of the window in screen coordinates. You can pass 0 
for window to determine the size of the entire workspace, that is, the smallest 
rectangle that encloses all active screens. 

x and y will be integers in the range from -2 15 to 2 15 -1; width and height will be 
integers in the range from 0 to 10000. 

Normally you should use the Window object’s getFrame: method instead of this 
operator (or the Application object’s getScreenSize: method, for the size of the 
screen). Use this operator only if you’re bypassing the Application Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

movewindow, placewindow 


currentwindowdepth window currentwindowdepth depth % internal 

Returns window's current depth. The invalidid error is executed if window doesn't 
exist. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

setwindowdepthlimit, currentwindowdepthlimit, setdefaultdepthlimit, 
currentdefaultdepthlimit 


currentwindowdepthlimit 

window currentwindowdepthlimit depth % internal 

Returns the window’s current depth limit, the maximum depth to which the 
window can be promoted. Unless altered by the setwindowdepthlimit operator, a 
window’s depth limit is equal to its context’s default depth limit. The invalidid 
error is executed if window doesn’t exist. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

setwindowdepthlimit, currentwindowdepth, setdefaultdepthlimit, 
currentdefaultdepthlimit 
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currentwindowdict 


window currentwindowdict diet % internal 


currentwindowlevel 


currentwriteblock 


Returns the specified window’s dictionary. Every window created by the 
Application Kit has a dictionary associated with it. Since the Application Kit uses 
this dictionary internally, direct manipulation of it will probably cause errors. 
Avoid calling this operator. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

setwindowdict 


window currentwindowlevel level 

Returns window's tier. Executes the invalidid error if window doesn't exist. 
ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

setwindowlevel 


- currentwriteblock bool 

Returns whether the Window Server delays sending data to a client application 
whenever the Server’s output buffer fills, currentwriteblock assumes the current 
context. If bool is true, the Server waits until the buffer can accept more data. If 
bool is false, the Server discards data that can’t be accepted immediately. 

SEE ALSO 

setwriteblock 
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dissolve 


src x src-y width height srcgstate dest x dest y delta dissolve - 


dumpwindow 


dumpwindows 


The effect of this operation is a blending of a source and a destination image. The 
first seven arguments choose source and destination pixels as they do for 
composite. The exact fraction of the blend is specified by delta , which is a 
floating-point number between 0.0 and 1.0; the resulting image is: 

delta * source + (1- de/ta)*destination 

If srcgstate is null, the current graphics state is assumed. If srcgstate or the current 
graphics state does not refer to a window device, this operator executes the 
invalidid error. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 
composite 


dumplevel window dumpwindow - % internal 

Prints information about window to the standard output file. Only dumplevel 0 is 
implemented. The information printed is the position and number of bytes of 
backing storage for the window. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

dumpwindows 


dumplevel context dumpwindows - % internal 

Prints information about all windows owned by context to the standard output file. 
If context is 0, it prints information about all windows. Only dumplevel 0 is 
implemented. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

dumpwindow 
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erasepage - erasepage - % different in the NeXT implementation 

This standard PostScript operator has the following effect in the NeXT 
implementation of the Display PostScript system: It erases the entire window to 
opaque white. 

ERRORS 

invalidid 

SEE ALSO 

copypage, showpage 


findwindow x y place otherwindow findwindow x' / window bool 

findwindow starts from a given position in the screen list and searches for the 
uppermost window below the position that contains the point (x, y). The x and y 
values are given in screen coordinates. 

The starting position is determined by place and otherwindow. place can be Above 
or Below, and otherwindow is the window number of a window in the screen list. 
If you specify Above 0, findwindow checks all windows in the screen list. 

If a window containing the point is found, findwindow returns true, along with the 
window number and the corresponding location in the base coordinate system of 
the window. Otherwise, it returns false, and the values of x', y', and window are 
undefined. 

ERRORS 

rangecheck, stackunderflow, typecheck 


flushgraphics - flushgraphics - 

Flushes to the screen all drawing done in the current buffered window. If the 
current window is retained or nonretained, flushgraphics has no effect. 

Normally you should use the Window object’s flushWindow method instead of 
this operator. Use this operator only if you’re bypassing the Application Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 
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framebuffer 


frontwindow 


hidecursor 


index string framebuffer name slot unit romid x y width height maxdepth 

Provides information on the active frame buffer specified by index, where index 
ranges from 0 to countframebuffers-1. string must be large enough to hold the 
resulting name of the frame buffer, slot is the NeXTbus slot the frame buffer is 
physically occupying. If a board supports multiple frame buffers, unit uniquely * 
identifies the frame buffer within a slot. The ROM product code is returned in 
romid. The bottom left comer of the frame buffer is returned in x and y (relative to 
the screen coordinate system). The size of the frame buffer in pixels is returned in 
width and height, maxdepth is the maximum depth displayable on this frame buffer 
(for example, NX_TwentyFourBitRGB). 

The limitcheck error is executed if string isn’t large enough to hold name. The 
rangecheck error is executed if index is out of bounds. 

ERRORS 

limitcheck, rangecheck, stackunderflow, typecheck 

SEE ALSO 

countframebuffers 


- frontwindow window % internal 

Returns the window number of the frontmost window on the screen. If there aren’t 
any windows on the screen, frontwindow returns 0. 

ERRORS 

none 

SEE ALSO 

orderwindow 


- hidecursor - 

Removes the cursor from the screen. It remains in effect until balanced by a call to 

showcursor. 

ERRORS 

none 

SEE ALSO 

obscurecursor, showcursor 


. framebuffer 
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hideinstance * v width height hideinstance - 

In the current window, hideinstance removes any instance drawing from the 
rectangle specified by x, y, width , and height, x, y, width, and height are given in 
the window’s current coordinate system. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

newinstance, setinstance 


initgraphics - initgraphics - % different in the NeXT implementation 

This standard PostScript operator has these additional effects in the NeXT 
implementation of the Display PostScript system: 

• Sets the coverage parameter in the current window’s graphics state to 1 
(opaque) 

• Turns off instance drawing 

ERRORS 

none 

SEE ALSO 

hideinstance, newinstance, setalpha, setinstance 


machportdevice width height bbox matrix hostname portname pixelencoding machportdevice - 

Sets up a PostScript device that can provide a generic rendering service for 
device-control programs requiring page bitmaps from PostScript documents. For 
each rendered page, machportdevice sends a Mach message containing the page 
bitmap to a port that has been registered with the name server on the network. (See 
/usr/include/windowserver/printmessage.h for the structure used in the print 
message.) 

width and height are integers that determine the number of device pixels for the 
page, bbox is an array of integers in the form [llx lly urx ury ]. The array specifies 
the lower left and upper right comers of the rectangle in the device raster to use as 
the boundary of the imageable area. (For the common case where the entire raster 
is imageable, bbox may be expressed as a zero-length array, [ ], which 
machportdevice interprets as [0 0 width height].) machportdevice requires the 
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bounding box array bbox to be well formed and within the device pixel bounds of 
[0 0 width height ]; otherwise, a rangecheck results. The bitmap data is stored in 
x-axis major indexing order. The device coordinate of the lower left comer of the 
first pixel is (0,0), the coordinate of the next pixel is (1,0) and so on for the entire 
scanline. Scanlines are long-word aligned. 

matrix is the default transformation matrix for the device, hostname and portname 
are strings that together identify the port that will receive the Mach messages. 
pixelencoding is a dictionary describing the format for the image data rendered by 
the Window Server. It should contain these entries: 


Key 

samplesPerPixel 

Type 

integer 

Semantics 

Currently must be 1 

bitsPerSample 

integer 

Currently must be 1 or 2 

colorSpace 

integer 

Color space specification (see below) 

isPlanar 

boolean 

true if sample values are stored in separate 
arrays (currently must be false ) 

defaultHalftone 

dictionary 

Passed to sethalftone during device creation 
to set up device default halftone 

initialTransfer 

procedure 

Passed to settransfer during device creation 
to set up the initial transfer function for 
device 

jobTag 

integer 

Allows machportdevice to tag rendering 
jobs. This value is included in the jobTag 
field of all printpage messages generated by 
this device. 


The value of colorSpace in the pixel-encoding dictionary should be one of the 


following values, predefined in nextdict. 


Name Value 

NX_OneIsBlackColorSpace 0 

NX_OneIsWhiteColorSpace 1 

NX_RgbColorSpace 2 

NX_CmykColorSpace 5 


Description 

Monochromatic, high sample value 
is black. 

Monochromatic, high sample value 
is white. 

RGB, (1,1,1) is white. 

CMYK, (0,0,0,0) is white. 
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The current implementation of machportdevice supports only the following 
combinations of colorSpace and bitsPerSample: 

colorSpace bitsPerSample 

NX_OneIsBlackColorSpace 1 

NX_OneIsWhiteColorSpace 2 

These read-only pixel-encoding dictionaries are predefined in nextdict: 

Name Description 

NeXTLaser-300 NeXT Laser Printer at 300 dpi resolution 

NeXTLaser-400 NeXT Laser Printer at 400 dpi resolution 

NeXTMegaPixelDisplay Megapixel Display’s 2 bits-per-pixel gray 

portname is resolved from the nameserver on hostname by calling 
netname_look_up(). This occurs during the execution of machportdevice —not 
for each page—so be sure that the receiving port has been checked in using 
netname_check_in() prior to executing machportdevice. If the portname isn’t 
checked in on the given host, a rangecheck results. 

If hostname is of length 0, the local host is assumed. If it is equal to ‘ * ’, a broadcast 
lookup is performed by netname_look_up(). Note, however, that sending large 
pages to remote hosts causes considerable network traffic, while sending large 
pages to the local host won’t require any copying of physical memory. 

The pagebuffer data is passed out-of-line, appearing in the receiving application’s 
address space. (If the receiver is on the same host, the received pagebuffer 
references the same physical memory as the Window Server’s pagebuffer, and is 
mapped copy-on-write.) The application should use vm_deaIlocate() to release 
the pagebuffer memory when it’s no longer needed. The receiver must 
acknowledge receipt of the data by sending a simple msg_header_t (with msg_id 
== NX_PRINTPAGEMSGID) back to the remote_port passed in the print 
message. The Window Server will not continue executing the page description 
until acknowledgement is received. 

If more than one copy of the page is needed (through either the copypage or 
#copies mechanism) each copy is sent as a separate message. In this case the same 
pagebuffer will be sent in multiple messages. The letter, legal, and note page types 
are gracefully ignored. (In general, an effort is made to gracefully ignore all 
LaserWriter-specific commands, which are listed in Appendix D of the PostScript 
Language Reference Manual.) 

Messaging errors cause the invalidaccess error to be executed. 

EXAMPLES 

This example sets up a 400 dpi 8.5 by 11 inch page on a raster with upper left 
origin (as with the NeXT 400 dpi Laser Printer) and sends its print page 
messages to the port named “nip-123” on the local host: 
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/dpi 400 def 

/width dpi 8.5 mul cvi def 
/height dpi 11 mul cvi def 


width height % page bitmap dimensions in pixels 
[] % use it all 

[dpi 72 div 0 0 dpi -72 div 0 height] % device transform 
() (nlp-123) % host (local) & port 

NeXTLaser-400 % pixel-encoding description 

machportdevice 

This example sets up an 8 by 10 inch page on the same 8.5 by 11 inch page. It 
specifies a 400 dpi raster with 1/4 inch horizontal margins and 1/2 inch vertical 
margins: 

/dpi 400 def 

/width dpi 8.5 mul cvi def 
/height dpi 11 mul cvi def 
/topdots dpi .5 mul cvi def 
/leftdots dpi .25 mul cvi def 


width height % page bitmap dimensions in pixels 

[ 


leftdots 

topdots 

width leftdots sub 
height topdots sub 

] % imageable area of bounding box 

[ 


dpi 72 div 
0 
0 


dpi -72 div 
leftdots 
height topdots 

] 

() (nlp-123) 

NeXTLaser-400 
machportdevice 


sub 

% device transform 
% host (local) & port 
% pixel-encoding description 


Note that in this example, we’ve chosen to put the user space origin at the lower 
left comer of the imageable area ( leftdots , height-topdots ) in the device raster 
coordinate system. Usually, the imageable area is meant to correspond with the 
ultimate destination of the bits. For example, a printer may have a 
constant-sized pagebuffer with a fixed orientation in the paper path, but be able 
to accept various sizes of paper. In this case, the page bitmap size will always 
be fixed, but the imageable area and default device transformation can be 
adjusted to make the user space origin appear at the lower left comer of each 
printed page. 

ERRORS 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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movewindow 


newinstance 


nextrelease 


x y window movewindow - % internal 

Moves the lower left comer of the specified window to the screen coordinates (x, y). 
No portion of the repositioned window can have an x or y coordinate with an 
absolute value greater than 16000. The operands can be integer, real, or radix 
numbers; however, they are converted to integers in the Window Server by 
rounding toward 0. 

The window need not be the frontmost window. This operator doesn’t change 
window 's ordering in the screen list. 

Normally you should use the Window object’s moveTo:: method instead of this 
operator. Use this operator only if you’re bypassing the Application Kit. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

currentwindowbounds, placewindow 


- newinstance - 

Removes any instance drawing from the current window. 

ERRORS 

invalidid 

SEE ALSO 

hideinstance, setinstance 


- nextrelease string 

Returns version information about this release of the NeXT Window Server. 

ERRORS 

stackoverflow 

SEE ALSO 

osname, ostype 
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NextStepEncoding - NextStepEncoding array 

Pushes the NextStepEncoding vector on the operand stack. This is a 256-element 
array, indexed by character codes, whose values are the character names for those 
codes. See Chapter 6 of the NeXT Technical Summaries manual for a table listing 
the character names and corresponding characters of this vector. 

ERRORS 

stackoverflow 

SEE ALSO 

StandardEncodingVector 


obscurecursor - obscurecursor - 

Removes the cursor image from the screen until the next time the mouse is moved. 
It’s usually called in response to typing by the user, so the cursor won’t be in the 
way. If the cursor has already been removed due to an obscurecursor call, 
obscurecursor has no effect. 

ERRORS 

none 

SEE ALSO 

hidecursor, revealcursor 
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orderwindow 


place otherwindow window orderwindow - % internal 

Orders window in the screen list as indicated by place and otherwindow. place can 

be Above, Below, or Out. 

• If place is Above or Below, the window is placed in the screen list immediately 
above or below the window specified by otherwindow. 

• If place is Above or Below and otherwindow is 0, the window is placed above 
or below all windows in the screen list. 

• If place is Above or Below, otherwindow must be a window in the screen list; 
otherwise, the invalidid error is executed. 

• If place is Out, otherwindow is ignored, and the window is removed from the 
screen list, so it won’t appear anywhere on the screen. Windows that aren’t in 
the screen list don’t receive user events. 

Since the workspace is a window in the screen list, Below 0 will make the specified 
window disappear behind all other windows, including the workspace. To place a 
window just above the workspace window, you can use Above 
workspace Window. (workspaceWindow is a PostScript name whose value is the 
window number of the workspace window.) 

Note: orderwindow doesn’t change which window is the current window. 

Normally you should use the Window object’s order WindowrrelativeTo: method 
instead of the orderwindow operator. Use this operator only if you’re bypassing 
the Application Kit. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

frontwindow 
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osname - osname string 


Returns a string identifying the operating system of the Window Server’s current 
operating environment, osname is defined in the statusdict dictionary, a 
dictionary that defines operators specific to a particular implementation of the 
PostScript language. See the PostScript Language Reference Manual for more 
information on statusdict. osname can be executed as follows: 

statusdict /osname get exec 


The NeXT version of the Window Server returns the string: 

(NeXT Mach) 

ERRORS 

none 

SEE ALSO 

nextrelease, ostype 


ostype - ostype int 

Returns a number identifying the operating system of the Window Server’s current 
operating environment, ostype is defined in the statusdict dictionary, a dictionary 
that defines operators specific to a particular implementation of the PostScript 
language. See the PostScript Language Reference Manual for more information on 
statusdict. ostype can be executed as follows: 


statusdict /ostype get exec 


The NeXT version of the Window Server returns the number 3 to indicate the 
operating system is a variant of UNIX. 

ERRORS 

none 

SEE ALSO 

nextrelease, osname 
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placewindow 


x y width height window placewindow - % internal 

Repositions and resizes the specified window, effectively allowing it to be resized 
from any comer or point, x, y, width , and height are given in the screen coordinate 
system. No portion of the repositioned window can have an x or y coordinate with 
an absolute value greater than 16000; width and height must be in the range from 
0 to 10000. The four operands can be integer or real numbers; however, they are 
converted to integers in the Window Server by rounding toward 0. 

placewindow places the lower left comer of the window at (. x , y) and resizes it to 
have a width of width and a height of height. The pixels that are in the intersection 
of the old and new positions of the window survive unchanged (see Figure 4-2). 
Any other areas of the newly positioned window are filled with the window’s 
exposure color (see setexposurecolor). 


This is what the window 
looks like before placewindow 
is called. Notice which pixels 
survive unchanged after the 
call to placeWindow. This 
allows a window to be resized 
from any corner or point. 


Before placewindow 
Figure 4-2. placewindow 
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After placewindow 


After moving or resizing a window with placewindow, you must execute the 
initmatrix and initclip operators to reestablish the window’s default 
transformation matrix and default clipping path. 

Normally you should use the Window object’s placeWindow: method instead of 
the placewindow operator. The placeWindow: method reestablishes the 
window’s transformation matrix and clipping path for you. Use the placewindow 
operator only if you’re bypassing the Application Kit. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

currentwindowbounds, movewindow, setexposurecolor 
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playsound soundname priority playsound - 

Plays the sound soundname. The Window Server searches for a standard NeXT 
soundfile of the name 

soundname. snd 

The search progresses through the following directories in the order given, 
stopping when the sound is located. 

-/Library/Sounds 

/LocalLibrary/Sounds 

/NextLibrary/Sounds 

No error occurs if the soundfile isn’t found: The operator has no effect. 

The soundfile’s playback is assigned the priority level priority. The playback 
interrupts any currently playing sound of the same or lower priority level. 

ERRORS 

stackunderflow, typecheck 


posteventby context type xy time flags window subType miscO miscl context posteventbycontext bool 

Posts an event to the specified context. The nine parameters preceding the context 
parameter coincide with the NXEvent structure members (see dpsclient/events.h). 
The x and y coordinate arguments are passed directly to the receiving context 
without undergoing any transformations, window is the Window Server’s global 
window number. Returns true if the event was successfully posted to context, and 
false otherwise. 

You might use this operator to post an application-defined event to your own 
application. Use Mach messaging to communicate between applications. 

ERRORS 

stackunderflow, typecheck 
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read image x y width height procg [■■■ proc n _i ] string bool readimage - 

Reads the pixels that make up a rectangular image described by x, y, width, and 
height in the current window. (Most programmers should use NXReadBitmapO 
instead of this operator.) 

Usually the image is the rectangle that has a lower left comer of (x, y) in the current 
coordinate system and a width and height of width and height. If the axes have been 
rotated so that the sides of the rectangle are no longer aligned with the edges of the 
screen, the image is the smallest screen-aligned rectangle enclosing the given 
rectangle. In any case, the pixels included in the image are determined by the mles 
given in the Concepts manual, under “Imaging Conventions.” 

You would typically call sizeimage before readimage (sending it the same x, y, 
width, and height values you’ll use for readimage) to find out ncolors, the number 
of color components that readimage must read, bool is a boolean value that 
determines whether readimage reads the alpha component in addition to the color 
component(s) for each pixel. The total number of components to be read for each 
pixel, together with the multiproc value returned by sizeimage, determine n, the 
number of procedures that readimage requires. If multiproc is false, n equals 1. 
Otherwise, n equals the number of color components plus the alpha component, if 
present. 

readimage executes the procedures in order, 0 through n-1, as many times as 
needed. For each execution, it pushes on the operand stack a substring of string 
containing the data from as many scanlines as possible. The length of the substring 
is a multiple of 

width * bits/sample * {samples!proc) / 8 

rounded up to the nearest integer. (The width and bits!sample values are provided 
by the sizeimage operator, samples is the number of color components plus 1 for 
the alpha component, if present.) 

The samples are ordered and packed as they are for the image, colorimage, or 
alphaimage operator. For example, the alpha component is last and, if necessary, 
extra bits fill up the last character of every scanline. Note that the contents of string 
are valid only for the duration of one call to one procedure because the same string 
is reused on each procedure call. The rangecheck error is executed if string isn’t 
long enough for one scanline. 

ERRORS 

rangecheck, stackunderflow, typecheck 
SEE ALSO 

alphaimage, sizeimage 
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renderbands 


proc renderbands - % undefined 


revealcursor 


rightbuttondown 


rightstilldown 


This standard PostScript operator is not defined in the NeXT implementation of the 
Display PostScript system. 


- revealcursor - 

Redisplays the cursor that was hidden by a call to obscurecursor, assuming that 
the cursor hasn’t already been revealed by mouse movement. If the cursor hasn’t 
been removed from the screen by a call to obscurecursor, revealcursor has no 
effect. 

ERRORS 

none 

SEE ALSO 

obscurecursor 


- rightbuttondown bool 

Returns true if the right mouse button is currently down; otherwise it returns false. 

Note: To test whether the right mouse button is still down from a mouse-down 
event, use rightstilldown instead of rightbuttondown; rightbuttondown will 
return true even if the mouse button has been released and pressed again since the 
original mouse-down event. 

ERRORS 

none 

SEE ALSO 

buttondown, currentmouse, rightstilldown, stilldown 


eventnum rightstilldown bool 

Returns true if the right mouse button is still down from the mouse-down event 
specified by eventnum ; otherwise it returns false, eventnum should be the number 
stored in the data component of the event record for an event of type 

Rmousedown. 

ERRORS 

stackunderflow, typecheck 

SEE ALSO 

buttondown, currentmouse, rightbuttondown, stilldown 
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screenlist 


screentobase 


array context screenlist subarray 

Fills the array with the window numbers of all windows in the screen list that are 
owned by the PostScript context specified by context. It returns the subarray 
containing those window numbers, in order from front to back. If array isn’t large 
enough to hold them all, this operator will return the frontmost windows that fit in 
the array. 

If context is 0, all windows in the screen list are returned. 

EXAMPLE 

This example yields an array containing the window numbers of all windows 
in the screen list that are owned by the current PostScript context: 

currentcontext 
countscreenlist 
array 

currentcontext screenlist 

ERRORS 

invalidaccess, invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

countscreenlist, countwindowlist, windowlist 


find out how many windows 
create array to hold them 
fill it in 


xy screentobase x'y' 

Converts (x, y) from the screen coordinate system to the current window’s base 
coordinate system. If the current device isn’t a window, the invalidid error is 
executed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

basetocurrent, basetoscreen, currenttobase, currenttoscreen, 
screentocurrent 
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screentocurrent xy screentocurrent x'y' 

Converts (x, y) from the screen coordinate system to the current coordinate system 
of the current window. If the current device isn’t a window, the invalidid error is 
executed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

basetocurrent, basetoscreen, currenttobase, currenttoscreen, 
screentobase 


setactiveapp context setactiveapp - % internal 

Records the active application’s main (usually only) context, setactiveapp is used 
by the window packages to assist with wait cursor operation. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

currentactiveapp 


setalpha coverage setalpha - 

Sets the coverage parameter in the current window’s graphics state to coverage, 
coverage must be a number between 0 and 1, with 0 corresponding to transparent, 
1 corresponding to opaque, and intermediate values corresponding to partial 
coverage. This establishes how much background shows through for purposes of 
compositing. 

ERRORS 

stackunderflow, typecheck, undefined 

SEE ALSO 

composite, currentalpha, setgray, sethsbcolor, setrgbcolor 


screentocurrent 
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setautofill bool window setautofill - 


setcursor 


Applies only to nonretained windows; sets the autofill property of window to true 
ox false. If true, newly exposed areas of the window or areas created by 
placewindow will automatically be filled with the window’s exposure color. If 
false, these areas will not change (typically they will continue to contain the image 
of the last window in that area). If the current device is not a window, this operator 
executes the invalidid error. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

placewindow, setexposurecolor, setsendexposed 


xymxmy setcursor - 

Sets the cursor image and hot spot. Rather than executing this operator directly, 
you’d normally use a NXCursor object to define and manage cursors. 

A cursor image is derived from a 16-pixel-square image in a window that’s 
generally placed off-screen. The x and y operands specify the upper left comer of 
the image in the window’s current coordinate system. The mx and my operands 
specify the relative offset (in units of the current coordinate system) from (x, y) to 
the hot spot, the point in the cursor that coincides with the mouse location. 
Assuming the current coordinate system is the base coordinate system, mx must be 
an integer from 0 to 16, and my must be an integer from 0 to -16. After setcursor 
is executed, the image in the window is no longer needed. 

The cursor is placed on the screen using Sover compositing. The cursor’s opaque 
areas (alpha =1) completely cover the background, while its transparent areas 
(alpha < 1) allow the background to show through to a greater extent depending on 
the alpha values present in the cursor image. 

Note: To make the off-screen window transparent, you can use compositerect 
with Clear. 

The rangecheck error is executed if the image doesn’t lie entirely within the 
specified window or if the point (mx, my) isn’t inside the image. If the current 
device isn’t a window, the invalidid error is executed. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

hidecursor, obscurecursor, setmouse 
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setdefaultdepthlimit depth setdefaultdepthlimit - % internal 


Sets the current context’s default depth limit to depth. The Window Server assigns 
each new context a default depth limit equal to the maximum depth supported by 
the system. When a new window is created, its depth limit is set to its context’s 
default depth limit. 

These depths are defined in nextdict: 


Depth 

NX_TwoBitGray 
NX_EightB itGray 
NX_Twel veB itRGB 
NX_TwentyFourBitRGB 


Meaning 

1 spp, 2bps, 2bpp, planar 
1 spp, 8bps, 8bpp, planar 
3 spp, 4bps, 16bpp, interleaved 
3 spp, 8bps, 32bpp, interleaved 


where spp is the number of samples per pixel; bps is the number of bits per sample; 
and bpp is the number of bits per pixel, also known as the window’s depth. (The 
samples-per-pixel value excludes the alpha sample, if present.) planar and 
interleaved refer to how the sample data is configured. If a separate data channel 
is used for each sample, the configuration is planar. If data for all samples is stored 
in a single data channel, the configuration is interleaved. 


When an alpha sample is present, the number of bits per pixel doubles for planar 
configurations (4 for NX_TwoBitGray and 16 for NX_EightBitGray). Interleaved 
configurations already account for an alpha sample whether or not it’s present; 
thus, the number of bits per pixel for NX_TwelveBitRGB and 
NX_TwentyFourBitRGB depths remains unchanged. 


The constant NX_DefaultDepth is also available. If depth is NX_DefaultDepth, 
the context’s default depth limit is set to the Window Server’s maximum visible 
depth, which is determined by which screens are active. 

The rangecheck error is executed if depth is invalid. 

ERRORS 

rangecheck, stackunderflow, typecheck 


SEE ALSO 

currentdefaultdepthlimit, setwindowdepthlimit, 
currentwindowdepthlimit, currentwindowdepth 


setdefaultdepthlimit 
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seteventmask 


mask window seteventmask - % internal 

Sets the Server-level event mask for the specified window to mask. For windows 
created by the window packages, this mask may allow additional event types 
beyond those requested by the application. The following operand names are 
defined for mask : 


mask 

Event Type Allowed 

Lmousedownmask 

Mouse-down, left or only mouse button 

Lmouseupmask 

Mouse-up, left or only mouse button 

Rmousedownmask 

Mouse-down, right mouse button 

Rmouseupmask 

Mouse-up, right mouse button 

Mousemovedmask 

Mouse-moved 

Lmousedraggedmask 

Mouse-dragged, left or only mouse button 

Rmousedraggedmask 

Mouse-dragged, right mouse button 

Mouseenteredmask 

Mouse-entered 

Mouseexitedmask 

Mouse-exited 

Keydownmask 

Key-down 

Keyupmask 

Key-up 

Flagschangedmask 

Flags-changed 

Kitdefinedmask 

Kit-defined 

Sysdefinedmask 

System-defined 

Appdefinedmask 

Application-defined 

Allevents 

All event types 


Normally you should use the Window object’s setEventMask: method instead of 
the seteventmask operator. Use this operator only if you’re bypassing the 
Application Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

currenteventmask 
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setexposurecolor - setexposurecolor - 

Applies to nonretained windows only; sets the exposure color to the color specified 
by the current color parameter in the current graphics state. The exposure color 
(white by default) determines the color of newly exposed areas of the window and 
of new areas created by placewindow. The alpha value of these areas is always 1 
(opaque). If the current device is not a window, this operator executes the invalidid 
error. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

placewindow, setautofill, setsendexposed 


setflushexposures bool setflushexposures - % internal 

Sets whether window-exposed and screen-changed subevents are flushed to clients. 
If bool is false, no window-exposed or screen-changed events are flushed to the 
client until setflushexposures is executed with bool equal to true. By default, 
window-exposed and screen-changed events are flushed to clients. 

ERRORS 

invalidid, stackunderflow, typecheck 


setinstance bool setinstance - 

Sets the instance-drawing mode in the current graphics state on (if bool is true) or 
off (if bool is false). 

ERRORS 

stackunderflow, typecheck 

SEE ALSO 

hideinstance, newinstance 


setexposurecolor 
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setmouse 


xy setmouse - 


Moves the mouse location (and, correspondingly, the cursor) to (x, y), given in the 
current coordinate system. If the current device isn’t a window, the invalidid error 
is executed. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

adjustcursor, basetocurrent, currentmouse, screentocurrent 


setowner context window setowner - 

Sets the owning PostScript context of window to context . The window is 
terminated automatically when context is terminated. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

currentowner, termwindow, window 


setpattern patternname setpattern - 

Sets the current pattern parameter in the graphics state to patternname. The pattern 
overrides the current color in the graphics state. Pattern drawing is automatically 
disabled when any other operator sets the current color in the graphics state (for 
example, setgray, setrgbcolor, or setalpha). This operator should be used for 
drawing user interface elements that can’t be drawn in one of the four pure gray 
values. By using a dither pattern rather than an intermediate shade of gray, you 
avoid having windows promoted to greater depths on the basis of standard 
user-interface features. For example, Scroller uses a pattern to draw the gray shade 
behind the knob. 

Only the following three patterns (defined in nextdict) are permitted: 

NX_MediumGrayPattern (50% dither of .333 and .666 gray) 

NXJLightGrayPattem (50% dither of .666 and 1.0 gray) 

NX_DarkGrayPattem (50% dither of 0 and .333 gray) 

The setpattern operator only works if the current device is a window; if it’s 
something other than a window (such as a printer, as set by machportdevice) an 
error occurs. 
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setsendexposed 


settrackingrect 


This operator will be superseded by PostScript Level 2’s setpattern operator. (The 
above patterns will continue to work, however.) 

ERRORS 

invalidid, stackunderflow 

SEE ALSO 

adjustcursor, basetocurrent, currentmouse, screentocurrent 


bool window setsendexposed - % internal 

Controls whether the Window Server generates a window-exposed subevent (of the 
kit-defined event) for window under the following circumstances: 

• Nonretained window: When an area of the window is exposed, or a new area 
is created by placewindow 

• Retained or buffered window: When an area of the window that had instance 
drawing in it is exposed 

By default, window-exposed subevents are generated under these circumstances. 
In any case, the window-exposed subevent isn’t flushed to the application until the 
Window Server receives another event. 

ERRORS 

invalidid, stackunderflow, typecheck 
SEE ALSO 

setflushexposures, placewindow, setautoflll, setexposurecolor 


x y width height leftbool rightbool insidebool userdata trectnum gstate 

settrackingrect - 

Sets a tracking rectangle in the window referred to by gstate to the rectangle 
specified by x, y, width , and height (in the coordinate system of that graphics state). 
(If gstate is null, the window referred to by the current graphics state is used.) The 
application will thereafter receive mouse-exited and mouse-entered events as the 
cursor leaves and reenters the visible portion of the tracking rectangle. Any 
number of tracking rectangles may be set in a single window. 

Note: You normally use the Window class’s 

setTrackingRect:inside:owner:tag:left:right: method for general cursor 
tracking. To track the cursor and change its image based on its location, you’d 
normally use the Window class’s cursor management methods such as 
addCursorRect:cursor:forView:. 
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setwaitcursorenabled 


trectnum is an arbitrary integer that can be any number except 0. It’s used to 
identify tracking rectangles; no two tracking rectangles can share the same 
trectnum value. In the event record for a mouse-exited or mouse-entered event 
generated as a result of this call to settrackingrect, the data component will 
contain trectnum along with the event number of the last mouse-down event. 

userdata is also an arbitrary integer that you assign to a tracking rectangle. 
However, since several tracking rectangles can share the same userdata value, you 
can use userdata to identify an object in your application that will be notified when 
a mouse-entered or mouse-exited event occurs in any of the tracking rectangles. 

The tracking rectangle will remain in effect until cleartrackingrect is called, or 
until another tracking rectangle with the same trectnum is set. 

You can specify that mouse-entered and mouse-exited events be generated only if 
certain mouse buttons are down. If leftbool is true , the events will be generated 
only when the left mouse button is down; likewise for rightbool and the right mouse 
button. If both leftbool and rightbool are true , the events will be generated only if 
both mouse buttons are down. If both leftbool and rightbool are false, the position 
of the mouse buttons isn’t taken into account in generating mouse-entered and 
mouse-exited events. 

settrackingrect causes the Window Server to repeatedly compare the current 
cursor position to the previous one to see whether the cursor has moved from inside 
the tracking rectangle to outside it or vice versa, insidebool tells settrackingrect 
whether to consider the initial cursor position to be inside or outside the tracking 
rectangle: 

• If insidebool is true and the cursor is initially outside the tracking rectangle, a 
mouse-exited event is generated. 

• If insidebool is false and the cursor is initially inside the tracking rectangle, a 
mouse-entered event is generated. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

cleartrackingrect 


bool context setwaitcursorenabled - 

Allows applications to enable and disable wait cursor operation in the specified 
context. If context is 0, setwaitcursorenabled sets the global wait cursor flag, 
which overrides all per-context settings. If the global flag is set to false, the wait 
cursor is disabled for all contexts. 
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setwindowdepthlimit 


ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

currentwaitcursorenabled 


depth window setwindowdepthlimit - % internal 

Sets the depth limit of window to depth. These depths are defined in nextdict: 


Depth 

NX_TwoBitGray 
NX_EightB itGray 
NX_Twel veB itRGB 
NX_TwentyFourB itRGB 


Meaning 

1 spp, 2bps, 2bpp, planar 
1 spp, 8bps, 8bpp, planar 
3 spp, 4bps, 16bpp, interleaved 
3 spp, 8bps, 32bpp, interleaved 


where spp is the number of samples per pixel; bps is the number of bits per sample; 
and bpp is the number of bits per pixel, also know as the window’s depth. (The 
samples-per-pixel value excludes the alpha sample, if present.) planar and 
interleaved refer to how the sample data is configured. If a separate data channel 
is used for each sample, the configuration is planar. If data for all samples is stored 
in a single data channel, the configuration is interleaved. 

When an alpha sample is present, the number of bits per pixel doubles for planar 
configurations (4 for NX_TwoBitGray and 16 for NX_EightBitGray). Interleaved 
configurations already account for an alpha sample whether or not it’s present; 
thus, the number of bits per pixel for NX_TwelveBitRGB and 
NX_TwentyFourB itRGB depths remains unchanged. 

Another constant, NX_DefaultDepth, is defined as the default depth limit in the 
Window Server’s current context. If depth is NX_DefaultDepth, then the window’s 
depth limit is set to the context’s default depth limit. If the resulting depth is lower 
than the window’s current depth, the window’s data is dithered down to this depth, 
which may result in the loss of graphic information. 

The rangecheck error is executed if depth is invalid. The invalidid error is 
executed if window doesn’t exist. 


ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

currentwindowdepthlimit, setdefaultdepthlimit, 
currentdefaultdepthlimit, currentwindowdepth 
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setwindowdict diet window setwindowdict - % internal 

Sets the dictionary for window to diet. This is usually done by the Application Kit. 

Every window created by the Application Kit has a dictionary associated with it. 
Since the Application Kit uses this dictionary internally, direct manipulation of it 
will probably cause errors. Avoid using this operator. 

ERRORS 

invalidid, stackunderllow, typecheck 

SEE ALSO 

currentwindowdict 


setwindowlevel level window setwindowlevel - 

Sets the window’s tier to that specified by level. Window tiers constrain the action 
of the orderwindow operator; see orderwindow for more information. 

You rarely use this operator. To make a panel float above other windows, use the 
Panel class’s setFloatingPanel: method. 

Attempting to change the level of workspaceWindow executes the invalidaccess 
error. (workspaceWindow is a PostScript name whose value is the window 
number of the workspace window.) 

ERRORS 

invalidaccess, invalidid, rangecheck, stackunderflow, typecheck 
SEE ALSO 

currentwindowlevel, orderwindow 


setwindowtype type window setwindowtype - 

Sets the window’s buffering type to that specified. Currently, the only allowable 
type conversions are from Buffered to Retained and from Retained to Buffered. All 
other possibilities execute the limitcheck error. 

ERRORS 

invalidaccess, invalidid, limitcheck, stackunderflow, typecheck 

SEE ALSO 

window 


4-40 Chapter 4: PostScript Operators 



setwriteblock bool setwriteblock - 


showcursor 


Sets how the Window Server responds when its output buffer to a client application 
fills. If bool is true, the Server defers sending data (event records, error messages, 
and so on) to that application until there’s once again room in the output buffer. In 
this way, no output data is lost—this is the Server’s default behavior. If bool is 
false, the Server ignores the state of the output buffer: If the buffer fills and there’s 
more data to be sent, the new data is lost, setwriteblock operates on the current 
context. 

Most programmers won’t need to use this operator. If you do use it, make sure that 
you disable the Window Server’s default behavior only during the execution of 
your own PostScript code. If it’s disabled while Application Kit code is being 
executed, errors will result. 

ERRORS 

stackoverflow, typecheck 

SEE ALSO 

currentwriteblock 


- showcursor - 

Restores the cursor to the screen if it’s been hidden with hidecursor, unless an 
outer nested hidecursor is still in effect (because it hasn’t yet been balanced by a 
showcursor). For example: 

% cursor is showing initially 
hidecursor % hides the cursor 

hidecursor % cursor stays 
showcursor % cursor still 
showcursor % displays the 

ERRORS 
none 

SEE ALSO 

hidecursor 


hidden 

hidden due to first hidecursor 

cursor 


setwriteblock 


4-41 



showpage - showpage - % different in the NeXT implementation 

This standard PostScript operator has no effect if the current device is a window. 

ERRORS 

none 

SEE ALSO 

copypage, erasepage 


sizeimage xy width height matrix sizeimage pixelswide pixelshigh bits!sample matrix 
multiproc ncolors 

Returns various parameters required by the readimage operator when reading the 
image contained in the rectangle given by x, y, width, and height in the current 
window. (See readimage for more information.) 

pixelswide and pixelshigh are the width and height of the image in pixels. The 
operand matrix is filled with the transformation matrix from user space to the image 
coordinate system and pushed back on the operand stack. 

The other results of this operator describe the window device and are dependent on 
the window’s depth. Each pixel has ncolors color components plus one alpha 
component; the value of each component is described by bits!sample bits. If 
multiproc is true, readimage will need multiple procedures to read the values of 
the image’s pixels. Here are the values that sizeimage returns for windows of 
various depths: 


Window Depth 

ncolors 

bits/sample 

multiproc 

NX_TwoB itGray 

1 

2 

true 

NX_EightB itGray 

1 

8 

true 

NX_Twel veB itRGB 

3 

4 

false 

NX_Twenty FourB itRGB 

3 

8 

false 

ERRORS 




stackunderflow, typecheck 




SEE ALSO 





alphaimage, readimage 
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stilldown eventnum stilldown bool 


termwindow 


Returns true if the left or only mouse button is still down from the mouse-down 
event specified by eventnum; otherwise it returns false, eventnum should be the 
number stored in the data component of the event record for an event of type 

Lmousedown. 

ERRORS 

stackunderflow, typecheck 

SEE ALSO 

buttondown, currentmouse, rightbuttondown, rightstilldown 


window termwindow - % internal 

Marks window for destruction. If the window is in the screen list, it’s removed from 
the screen list and the screen. The given window number will no longer be valid; 
any attempt to use it will execute the invalidid error. The window will actually be 
destroyed and its storage reclaimed only after the last reference to it from a 
graphics state is removed. This can be done by resetting the device in the graphics 
state to another window or to the null device. 

Note: After you use the termwindow operator, if the terminated window had been 
the current window, you should use the nulldevice operator to remove references 
to it. 

Normally you should use the Window object’s close method instead of the 
termwindow operator. Use this operator only if you’re bypassing the Application 
Kit. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

window, windowdevice, windowdeviceround 
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window x y width height type window window % internal 

Creates a window that has a lower left comer of (x, y) and the indicated width and 
height, x, y, width, and height are given in the screen coordinate system. No 
portion of a window can have an x or y coordinate with an absolute value greater 
than 16000; width and height must be in the range from 0 to 10000. Exceeding 
these limits executes the rangecheck error. The four operands can be integer or 
real numbers; however, they are converted to integers in the Window Server by 
rounding toward 0. This operator returns the new window’s window number, a 
nonzero integer that’s used to refer to the window. 

type specifies the window’s buffering type as Buffered, Retained, or 
Nonretained. 

The new window won’t be in the screen list; you can put it there with the 
orderwindow operator. Windows that aren’t in the screen list don’t appear on the 
screen and don’t receive user events. 

The window operator also does the following: 

• Sets the origin of the window’s base coordinate system to the lower left comer 
of the window 

• Sets the window’s clipping path to the outer edge of the window 

• Fills the window with opaque white and sets the window’s exposure color to 
white 

Note: This operator does not make the new window the current window; to do that, 
use windowdeviceround or windowdevice. 

Normally you should use the Window object’s 

newContent:style:backing:buttonMask:defer: method instead of the window 
operator. Use this operator only if you’re bypassing the Application Kit. 

ERRORS 

invalidid, rangecheck, stackunderflow, typecheck 

SEE ALSO 

setexposurecolor, termwindow, windowdeviceround 
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windowdevice 


window windowdevice - 


windowdeviceround 


Sets the current device of the current graphics state to the given window device. It 
also sets the origin of the window’s default matrix to the lower left comer of the 
window. One unit in the user coordinate system is made equal to 1/72 of an inch. 
The clipping path is reset to a rectangle surrounding the window. Other elements 
of the graphics state remain unchanged. This matrix becomes the default matrix 
for the window: initmatrix will reestablish this matrix. 

windowdevice is rarely used in NeXTStep since the coordinate system it 
establishes isn’t aligned with the pixels on the screen. Use the related operator 
windowdeviceround to create a coordinate system that is aligned. 

Don’t use this operator lightly, as it creates a new matrix and clipping path. It’s 
significantly more expensive than a setgstate operator. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

windowdeviceround 


window windowdeviceround - 

Sets the current device of the current graphics state to the given window device. It 
also sets the origin of the window’s default matrix to the lower left comer of the 
window. One unit in the user coordinate system is made equal to the width of one 
pixel, approximately 1/92 inch. The clipping path is reset to a rectangle 
surrounding the window. Other elements of the graphics state remain unchanged. 
This matrix becomes the default matrix for the window: initmatrix will reestablish 
this matrix. 

Don’t use this operator lightly, as it creates a new matrix and clipping path. It’s 
significantly more expensive than a setgstate operator. 

ERRORS 

invalidid, stackunderflow, typecheck 

SEE ALSO 

windowdevice 


windowdevice 
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windowlist array context windowlist subarray 


Fills the array with the window numbers of all windows that are owned by the 
PostScript context specified by context. It returns the subarray containing those 
window numbers, in order from front to back. If array isn’t large enough to hold 
them all, this operator returns the frontmost windows that fit in the array. 

EXAMPLE 

This example yields an array containing the window numbers of all windows 
that are owned by the current PostScript context: 

currentcontext 

countwindowlist % find out how many windows 

array % create array to hold them 

currentcontext windowlist % fill it in 

ERRORS 

stackunderflow, typecheck 
SEE ALSO 

countscreenlist, countwindowlist, screenlist 
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Chapter 5 
Data Formats 


To make it easier for applications to share information, the NeXTStep pasteboard supports 
a small number of standard data formats. Each format, or type, is identified by a global 
variable: 


Type Description 
Plain ASCII text 


Variable Name 

NXAsciiPboardType 

NXPostScriptPboardType 

NXTIFFPboardType 

NXRTFPboardType 

NXSoundPboardType 

NXFilenamePboardType 

NXTabularTextPboardType 

NXFontPboardType 

NXRulerPboardType 


Encapsulated PostScript code (EPS) 
Tag Image File Format (TIFF) 

Rich Text Format (RTF) 

The Sound object’s pasteboard type 
ASCII text designating a file name 
Tab-separated fields of ASCII text 
Font and character information 
Paragraph formatting information 


Data in other formats can also be placed in the pasteboard. However, the sending and 
receiving applications must both agree on the structure of the format, its name, and how to 
interpret it. Other formats may be adopted as standards in the future. 


Each of the standard formats is discussed below. In most cases, the discussion is short and 
consists only of a reference to the primary source document for the format. In some cases, 
more information is given on modifications to or interpretations of the format in the 
NeXTStep environment. 


NXAsciiPboardType 

Text in this format consists only of characters from the ASCII character set as extended by 
NeXTStep encoding. None of the characters is given a special interpretation (in contrast to 
NXTabularTextPboardType and NXFilenamePboardType, for example). Standard ASCII 
is documented on-line in /usr/pub/ascii and the ascii(7) manual page. NeXTStep encoding 
is documented in Chapter 6 of the NeXT Technical Summaries manual. 


NXAsciiPboardType 
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NXPostScriptPboardType 


This type is defined as PostScript code in the Encapsulated PostScript Files format (EPS). 
The PostScript language is documented by Adobe Systems Incorporated, principally in the 
PostScript Language Reference Manual, published by Addison-Wesley. EPS conventions 
are documented in Encapsulated PostScript Files Specification, by Adobe Systems 
Incorporated. 


NXTIFFPboardType 

This type is for image data in Tag Image File Format (TIFF). TIFF is documented in Tag 
Image File Format Specification, by Aldus Corporation and Microsoft Corporation. 

TIFF support in the current NeXTStep release follows version 5.0 of the TIFF standard and 
is based on version 2.2 of Sam Leffler’s freely distributed TIFF library. This library 
provides a good set of routines for dealing with TIFF files that conform to the 5.0 
specification. 

NeXTStep TIFF support is embodied in the NXBitmapImageRep class and the 
command-line program tiffutil. See “NXBitmapImageRep” in Chapter 2, “Class 
Specifications” and the tiffutil manual page for more information. 


Unsupported Fields 

In the current release, some fields—principally those having to do with response curves— 
will be read correctly but ignored when imaging the data. Color palettes are not supported 
except when the palette entries are 8 bits and the stored colors are 24 bits. These files will 
be read correctly and converted to 24-bit images on the fly. 


The Matte Field 

The 5.0 TIFF specification has been extended to include a Matte field (tag 32995), which 
indicates the presence or absence of a coverage component (alpha) in the data. This field 
is a SHORT with a value of 1 or 0. A value of 1 indicates that a coverage component is 
present and that the color components are premultiplied by the alpha values. The coverage 
component follows the color components in the data. The absence of this field or a value 
of 0 indicates that no coverage component is present; the image is opaque. 

TIFF files generated by release 1.0 of NeXTStep did not contain a Matte field. Instead, to 
indicate the presence of a coverage component, the value of the SamplesPerPixel field was 
set to 2 and the value of the Photometriclnterpretation field was set to 5. Release 2.0 
software recognizes these files as containing alpha despite the lack of a Matte field. Thus 
all TIFF files generated by 1.0 software will be interpreted correctly. 
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Multiple Images 

Multiple forms of an image can now be stored in the same file—that is, under the same TIFF 
header. “Multiple forms” might mean the same image at different resolutions (for example, 
72dpi and 400dpi) and at different bit depths or colors (for example, 2 bits per sample on a 
gray scale and 4 bits per sample RGB). 

This feature is useful when you want to create color icons for an application and its 
documents. It’s best to create both gray scale and color versions of the icons and store them 
in the same section of the ICON segment. Both versions of the icon would be created at 
72 dpi and would be 48 pixels wide by 48 pixels high. The gray-scale version would have 
two components (gray and alpha), with each component stored at 2 bits. The color version 
would have 4 components (red, green, blue, and alpha) and each component would be 4 bits 
deep. (It’s recommended that application and document icons be stored at 4 bits per 
sample, not 8.) 


Compression 

NeXTStep software can both read and write compressed TIFF images. The Compression 
field in a TIFF file can have any of the following values: 

Compression Value Compression Type 

1 No compression 

5 LZW (Lempel-Ziv & Welch) compression 

32773 PackBits compression 

32865 JPEG compression 

JPEG compression can be used only for images that have a depth of at least 4 bits per 
sample. 


NXRTFPboardType 

This is the pasteboard type for “rich text,” text that follows the conventions of the Rich Text 
Format®, as described in Rich Text Format Specification by Microsoft Corporation. 

To this specification, NeXT has added a control word to indicate how the user selected the 
text before copying it to the pasteboard. The control word is 

\smartcopy<«Mm> 

where <num> can be 1 or 0. A value of 1 indicates that the user made the selection by 
double-clicking a word, or double-clicking and dragging over a group of words. The range 
of text in the pasteboard will be delimited by a word boundary on either side. The pasting 
application can use this information to correctly adjust the spacing around the word or 
words that are pasted. 
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NXSoundPboardType 


This format is defined by the SNDSoundStruct structure in the header file 
sound/soundstruct.h. The structure and the methods for writing sound data to and reading 
it from the pasteboard are discussed in more detail in Sound, Music, and Signal Processing. 


NXFilenamePboardType 

This format is a list of tab-separated file names (or pathnames), terminated by a null 
character (‘\0’). 


NXTabularTextPboardType 

This format is ASCII text where tabs (ASCII 0x09) and returns or newlines (ASCII OxOD) 
are interpreted as separators between text fields. In a matrix, tabs separate columns and 
returns separate rows. The text is null-terminated. 


NXFontPboardType 

This format is used in the font pasteboard to record character properties that are copied and 
pasted using the Copy Font and Paste Font commands. It consists of RTF control words 
from the “Font Table” and “Character Formatting Properties” groups. 

The following is an example of character data in this format: 


{\rtfl\ansi{\fonttbl\fO\froman Times;} 

\f0\b0\i\ul0\fs48} 

The first two control words, \rtfl and \ansi, announce that the information enclosed within 
the outer braces is RTF version 1 in ANSI character encoding. These two control words, 
or their equivalent, are required by RTF conventions. 

The group within the inner braces defines a font table, here with a single entry specifying 
font 0 to be Times-Roman. The font is then specified as Times-Roman (font 0), not bold, 
Oblique (italic), not underlined, and having a font size of 24 points (48 half points). 
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Among the fonts that can be specified in a font table are these: 


\fmodern Courier; 
\fswiss Helvetica; 
\fmodern Ohlfs; 
\ftech Symbol; 

\froman Times; 


Several synonyms are recognized for the Times-Roman font. Usually it’s written as 
“Times” or “Times-Roman”. 

If the font pasteboard contains RTF control words that don’t belong to the “Font Table” or 
“Character Formatting Properties” groups, they should be ignored. If control words specify 
more than one value for a font characteristic, the last value specified should be used when 
pasting. 


NXRuIerPboardType 

This format is used in the ruler pasteboard to capture information about how a paragraph is 
formatted. It consists of RTF control words from the “Paragraph Formatting Properties” 
group. 

The following is an example of this type: 

{\rtfl\ansi 

\pard\ql\txl252\tx2716\tx4148\tx5592\tx7004\txll520 

\fi-540\lil260} 

The first two control words are required by RTF conventions, as explained under 
“NXFontPboardType” above. The next control word, \pard, resets the paragraph format to 
the default. The paragraph is then specified to be left-aligned and a series of six tabs are 
set. Next, the indentation of the first line is specified and, finally, the left indent. (The 
example is for a paragraph with a hanging indent.) 

If the ruler pasteboard contains RTF control words that aren’t in the “Paragraph Formatting 
Properties” group, they should be ignored. If it includes control words that first set then 
reset a paragraph property, the final specification should be the one that’s used. 


NXRuIerPboardType 
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Index 


_aIloc() 3-164 
_copy() 3-164 
_dealloc() 3-164 
_error() 3-164 
_realIoc() 3-164 
_zoneAlIoc() 3-164 
_zoneCopy() 3-164 
zoneRealloc 3-164 

abortEditing method 2-183 
abortModal method 2-77 
acceptArrowKeys: method 2-327 
acceptColonatPoint: 2-361, 2-365, 2-678 
acceptsFirstMouse method 2-115, 2-273, 2-365, 
2-424, 2-502, 2-526, 2-644 
acceptsFirstResponder method 2-327, 2-484, 
2-570, 2-627 

accessoryView method 2-220, 2-440, 2-480, 2-494 
action method 2-66, 2-146, 2-183, 2-207, 2-273, 
2-327, 2-365, 2-461,2-502 
ActionCell class 

specification 2-65 
activate: method 2-77,2-366 
activateSelf: method 2-78 
activeApp method 2-78 
activeWellsTakeColorFrom: method 2-364 
active WellsTakeColorFromrcontinuous method 
2-365 

addCol method 2-273 
addColumn method 2-327 
addCursorRectrcursor: 2-644 
addCursorRect:cursor:forView: 2-690 
addElement: method 2-55 
addEntry: method 2-228 
addEntry:tag:target:action: 2-228 
addFontTrait: method 2-208 
addltem: method 2-461 
addItem:action:keyEquivalent: 2-298 
addObject: method 2-20 
addObjectlfAbsent: method 2-21 
addPort method 2-247 
addRow method 2-274 
addSubview: method 2-107, 2-644 
addSubview::relativeTo: 2-644 
addToEventMask: method 2-691 


addToPageSetup method 2-645 
addWindowsltem: title: filename: 2-7 8 
adjustcursor operator 4-1 
adjustPageHeightNew:top:bottom:limit: 2-570, 
2-645 

adjustPageWidthNew:left:right:limit: 2-645 
adjustScroll: method 2-646 
adjustSubviews method 2-424 
alignment method 2-146, 2-183, 2-571 
alignSelCenter: method 2-571 
alignSelLeft: method 2-571 
alignSelRight: method 2-572 
alloc method 2-33, 2-76, 2-197, 2-207, 2-219, 
2-358, 2-439, 2-454, 2-479, 2-494 
allocateGState method 2-646 
allocFromZone method 2-33, 2-358 
allocFromZone: method 2-76, 2-197, 2-207, 
2-219, 2-439, 2-454, 2-479, 2-494 
allowBranchSel: method 2-327 
allowEmptySel: method 2-274 
allowMultipleFiles: method 2-435 
allowMultiSel: method 2-328 
alphaimage operator 4-1 
altlcon method 2-115,2-128 
altlmage method 2-115,2-128 
altTitle method 2-115,2-128 
app:openFile:type: 2-100 
app:openTempFile:type: 2-100 
app:powerOffTn:andSave: 2-100 
app:unmounting: 2-101 
app Accepts AnotherFile: method 2-101 
appDidBecomeActive: method 2-101 
appDidHide: method 2-101 
appDidlnit: method 2-101 
appDidResignActive: method 2-101 
appDidUnhide: method 2-102 
appDidUpdate: method 2-102 
applcon method 2-79 
Application class 

specification 2-71 
Application Kit 
functions 3-3 

applicationDefined: method 2-79, 2-102 
appListener method 2-79 
appListenerPortName method 2-79 
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appName method 2-79 
appSpeaker method 2-80 
appWilllnit: method 2-102 
appWillTerminate: method 2-102 
appWillUpdate: method 2-102 
arrangelnFront: method 2-80 
autoscroll: method 2-169, 2-646 
availableFonts method 2-208 
awake method 2-39, 2-107, 2-146, 2-169, 2-199, 
2-298, 2-502, 2-522, 2-531, 2-646, 2-691 

backgroundColor method 2-169, 2-274, 2-391, 
2-512, 2-572, 2-627, 2-634, 2-691 
backgroundGray method 2-170, 2-274, 2-512, 
2-572, 2-627, 2-634, 2-692 
bandevice operator 4-2 
basetocurrent operator 4-3 
basetoscreen operator 4-3 
becomeActiveApp method 2-80 
becomeFirstResponder method 2-484, 2-572 
becomeKeyWindow method 2-572, 2-692 
becomeMain Window method 2-692 
beginModalSession:for: 2-80 
beginPage:label:bBox:fonts: 2-647, 2-692 
beginPageSetupRectrplacement: 2-647, 2-693 
beginPrologueBBox:creationDate:createdBy: 

fonts:forWhom:pages:title: 2-648, 2-693 
beginPSOutput method 2-649, 2-694 
beginSetup method 2-649, 2-694 
beginTrailer method 2-649,2-695 
bestRepresentation method 2-392 
bestScreen method 2-695 
bitsPerPixel method 2-312 
bitsPerSample method 2-412 
BOOL data type 1-8 
borderType method 2-107,2-512 
boundsAngle method 2-649 
Box class 

specification 2-105 
branchlcon method 2-346 
branchlconH method 2-346 
breakTable method 2-573 
browser:columnIsValid: 2-341 
browserDidScroll: method 2-342 
browser:fillMatrix:inColumn: 2-342 
browsengetNumRowsInColumn: 2-342 
browser:loadCell:atRow:inColumn: 2-342 
browser:selectCell:inColumn: 2-343 
browser:titleOfColumn: 2-343 
browserWillScroIl: method 2-343 
Button class 

specification 2-113 


ButtonCell class 
constants 2-140 
specification 2-123 
buttondown operator 4-3 
buttonMask method 2-695 
byteLength method 2-573 
bytesPerPlane method 2-312 
bytesPerRow method 2-313 

C functions 3-3 

NeXTStep functions 3-3 
run-time functions 3-148 
single-operator functions 3-141 
Cache data type 1-8 
calcCellSize: method 2-146, 2-616 
calcCellSize:inRect: 2-128, 2-147, 2-236, 2-346, 
2-522, 2-531 

calcDrawInfo: method 2-147 
calcLine method 2-573 
calcParagraphStyle:: 2-574 
calcRect:forPart: 2-502 
calcSize method 2-183, 2-228, 2-274 
calcTargetForAction: method 2-81 
calcUpdateRects:::: 2-650 
canBecomeKeyWindow method 2-695 
canBecomeMainWindow method 2-696 
cancel: method 2-494 
canDraw method 2-650 
canStoreColor method 2-696 
capacity method 2-21 
Category data type 1-8 
Cell class 

constants 2-165 
specification 2-141 
cell method 2-107,2-183 
cellAt:: 2-274 

cellBackgroundColor method 2-275 
cellBackgroundGray method 2-275 
cellCount method 2-275 
cellList method 2-275 
cellPrototype method 2-328 
center method 2-696 
centerScanRect: method 2-650 
changeButtonTitle: method 2-461 
changeCount method 2-455 
changeFont: method 2-574 
changePrinter: method 2-480 
changeTabStopAt:to: 2-574 
changeWindows:title:filename: 2-81 
charCategoryTable method 2-574 
charFilter method 2-575 
charWrap method 2-575 
checklnAs: method 2-248 
checkout method 2-248 
checkSpaceForParts method 2-503 
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checkSpelling: method 2-575 
Class data type 1-8 
class method 2-34, 2-40 
class_addClassMethods() 3-151 
class_addInstanceMethods() 3-151 
class_createlnstance() 3-149 
class_createInstanceFromZone() 3-149 
class_getClassMethod() 3-151 
class_getInstanceMethod() 3-151 
class_getlnstanceVariable() 3-152 
class_getVersion() 3-153 
class_poseAs() 3-152 
class_removeMethods() 3-151 
class_setVersion() 3-153 
clear: method 2-575 
cleardictstack operator 4-4 
clearSelectedCell method 2-275 
clearTitleInRect:ofColumn: 2-328 
cleartrackingrect operator 4-4 
clickTable method 2-575 
client library functions 3-3 
clipToFrame: method 2-651 
ClipView class 

specification 2-167 
close method 2-298, 2-696 
color method 2-358, 2-366 
colorMask method 2-358 
colorScreen method 2-81 
colorSpace method 2-313 
columnOf: method 2-328 
columnsAreSeparated method 2-328 
commandKey: method 2-447, 2-494, 2-697 
composite operator 4-5 
composite:fromRect:toPoint: 2-392 
composite:toPoint: 2-392 
compositerect operator 4-7 
constants 1-3 

constrainFrameRect:toScreen: 2-697 
constrainScroll: method 2-170 
content View method 2-107,2-698 
context method 2-81, 2-468 
continueTracking:at:inView: 2-147, 2-531 
Control class 

specification 2-179 
control View method 2-67, 2-147 
convert:toFamily: 2-208 
convert:toHaveTrait: 2-209 
convert:toNotHaveTrait: 2-209 
convertBaseToScreen: method 2-698 
convertFont: method 2-209 
convertOldFactor: newFactor: 2-440 
convertPoint:fromView: 2-651 
convertPoint:toView: 2-651 
convertPointFromSuperview: 2-652 


convertPointToSuperview: method 2-652 
convertRect:fromView: 2-652 
convertRect:toView: 2-652 
convertRectFromSuperview: method 2-652 
convertRectToSuperview: method 2-652 
convertScreenToBase: method 2-698 
convertSize:fromView: 2-653 
convertSize:toView: 2-653 
convertWeight:of: 2-209 
copies method 2-468 

copy method 2-15, 2-21, 2-40, 2-55, 2-148, 2-236, 
2-313,2-381,2-634 
copy: method 2-576 
copyFont: method 2-576 
copyFromZone method 2-129 
copyFromZone: method 2-15, 2-21, 2-40, 2-55, 
2-148 

copypage operator 4-7 
copyPSCodeInside:to: 2-653, 2-698 
copy Ruler: method 2-576 
count method 2-15,2-21,2-55,2-461 
countframebuffers operator 4-8 
countscreenlist operator 4-8 
countwindowlist operator 4-8 
currentactiveapp operator 4-9 
currentalpha operator 4-9 
currentCursor method 2-371 
currentdefaultdepthlimit operator 4-9 
currentdeviceinfo operator 4-9 
currentEditor method 2-184 
currentEvent method 2-81 
currenteventmask operator 4-10 
currentmouse operator 4-10 
currentowner operator 4-10 
currentPage method 2-469 
currentrusage operator 4-11 
currenttobase operator 4-11 
currenttoscreen operator 4-11 
currentuser operator 4-12 
currentwaitcursorenabled operator 4-12 
currentwindow operator 4-12 
currentwindowalpha operator 4-12 
currentwindowbounds operator 4-13 
currentwindowdepth operator 4-13 
currentwindowdepthlimit operator 4-13 
currentwindowdict operator 4-14 
currentwindowlevel operator 4-14 
currentwriteblock operator 4-14 
cut: method 2-577 

data formats 5-3 
data method 2-313 
datatypes 1-8 
deactivate method 2-366 
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deactivateAUWells method 2-365 
deactivateSelf method 2-82 
declareTypesmum:owner: 2-455 
defaultDepthLimit method 2-689 
defaultParaStyle method 2-577 
delayedFree: method 2-82 
delegate method 2-82, 2-248, 2-329,2-393,2-419, 
2-425,2-542, 2-577, 2-699 
delete: method 2-578 
deminiaturize: Method 2-699 
depthLimit method 2-699 
descendantFlipped: method 2-170, 2-653 
descendantFrameChanged: method 2-170, 2-654 
descentLine method 2-578 
description method 2-55 
directory method 2-494 
disableCursorRects method 2-699 
disableDisplay method 2-700 
disableFlushWindow method 2-700 
discardCursorRects method 2-654, 2-700 
discardTrackingRect: method 2-701 
display method 2-115, 2-275, 2-298, 2-654, 2-701 
Display PostScript See PostScript 
display:: 2-654 
display::: 2-655 

displayAllColumns method 2-329 
displayBorder method 2-701 
display Column: method 2-329 
displayFromOpaqueAncestor ::: 2-655 
displayIfNeeded method 2-656, 2-701 
dissolve operator 4-15 
dissolve:fromRect:toPoint: 2-393 
dissolve:toPoint: 2-394 
dividerHeight method 2-425 
doClick: method 2-329 
doc View method 2-171,2-513 
doDoubleClick: method 2-329 
doesAutosizeCells method 2-276 
doesBecomeKeyOnlylfNeeded method 2-447 
doesClip method 2-656 
doesHideOnDeactivate method 2-701 
doesNotRecognize: method 2-40 
doubleAction method 2-276, 2-330 
doubleValue method 2-67, 2-129, 2-148, 2-184, 
2-531 

doubleValueAt: method 2-228 
“DPS” functions 

client library functions 3-3 
single-operator functions 3-141 
DPSAddFDO 3 4 
DPSAddPort() 3-5 
DPSAddTimedEntryO 3-6 
DPSBinObjGeneric data type 1-9 
DPSBinObjReal data type 1-9 


DPSBinObjRec data type 1-8 
DPSBinObjSeqRec data type 1-9 
DPSContextRec data type 1-10 
DPSContextType data type 1-10 
DPSCreateContextO 3-7 
DPSCreateContextWithTimeoutFromZoneO 
3-7 

DPSCreateStreamContextO 3-7 
DPSDefinedType data type 1-10 
DPSDefineUserObject() 3-9 
DPSDiscardEventsO 3-13 
DPSDoUserPath() 3-10 
DPSDoUserPathWithMatrix() 3 10 
DPSErrorCode data type 1-11 
DPSErrorProc data type 1-11 
DPSEventFilterFunc data type 1-11 
DPSExtendedBinObj Seq data type 1-11 
DPSFDProc data type 1-12 
DPSFIush() 3-12 
DPSGetEventO 3-13 
DPSNameEncoding data type 1-12 
DPSNameFromTypeAndlndexO 3-15 
DPSNumberFormat data type 1-12 
DPSPeekEventO 3-13 
DPSPortProc data type 1-12 
DPSPostEvent() 3-15 
DPSPrintError() 3-16 
DPSPrintErrorToStream() 3-16 
DPSProcs data type 1-12 
DPSProgramEncoding data type 1-13 
DPSRemoveFD() 3-4 
DPSRemovePort() 3-5 
DPSRemoveTimedEntryO 3-6 
DPSResultsRec data type 1-13 
DPSSetDeadKeysEnabled() 3-17 
DPSSetEventFunc() 3-18 
DPSSetTrackingO 3-19 
DPSSpaceProcsRec data type 1-14 
DPS SpaceRec data type 1-14 
DPSStartWaitCursorTimer() 3-19 
DPSTextProc data type 1-14 
DPSTimedEntry data type 1-14 
DPSTVaceContextO 3-20 
DPSTraceEvents() 3-21 
DPSUndefineUserObjectO 3-9 
DPSUserPathAction data type 1-15 
DPSUserPathOp data type 1-15 
dragColor:withEvent:fromView: 2-356 
dragFile:fromRect:sIideBack:event: 2-656 
dragFrom::eventNum: 2-702 
draw method 2-314, 2-350, 2-376, 2-382, 2-412 
drawArrow:: 2-503 
drawAt: method 2-412 
drawBarInside:flipped: 2-531 
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drawCell: method 2-184, 2-276 
drawCellAt: method 2-228 
drawCell At:: 2-276 
drawCelllnside: method 2-184, 2-276 
drawDivider: method 2-425 
drawFunc method 2-578 
drawln: method 2-314,2-382,2-413 
drawInside:inView: 2-129, 2-148, 2-237, 2-347, 
2-522, 2-532, 2-635 
drawInSuperview method 2-657 
drawKnob method 2-503, 2-532 
drawKnob: method 2-532 
drawPageBorder:: 2-657 
drawParts method 2-503 
drawRepresentation:inRect: 2-394 
drawSelf:: 2-171 

drawSelf:: 2-108, 2-184, 2-276, 2-330, 2-366, 
2-425, 2-504, 2-513, 2-578, 2-657 
drawSelf: in Vie w: 2-67, 2-129, 2-149, 2-237, 
2-347, 2-522, 2-532, 2-616, 2-635 
drawSheetBorder:: 2-658 
drawTitle:inRect:ofColumn: 2-330 
drawWelllnside: method 2-366 
dumpwindow operator 4-15 
dump windows operator 4-15 

edit:inView:editor:delegate:event: 2-149 
elementAt: method 2-56 
empty method 2-15, 2-22, 2-56 
enableCursorRects method 2-702 
endEditing: method 2-149 
endEditingFor: method 2-702 
endHeaderComments method 2-658, 2-703 
endModalSession: method 2-82 
endPage method 2-658, 2-703 
endPageSetup method 2-658, 2-703 
endPrologue method 2-659, 2-704 
endPSOutput method 2-659, 2-704 
endSetup method 2-659, 2-704 
endTrailer method 2-659, 2-704 
entryType method 2-149 
erasepage operator 4-16 
error: method 2-41 
error Action method 2-276, 2-628 
eventMask method 2-704 
excludeFromServicesMenu: method 2-568 
extendPowerOffBy.actual: 2-248, 2-542 

faxPSCode: method 2-660, 2-705 

filename method 2-495 

filenames method 2-435 

find Ancestor Shared With: method 2-660 

findCellWithTag: method 2-277, 2-299 

findFont:traits:weight:size: 2-210 


findlmageNamed: method 2-390 
findlndexWithTag: method 2-229 
find View WithTag: method 2-660 
findwindow operator 4-16 
findWindow: method 2-82 
finishLoading: method 2-34 
finishReadingRichText method 2-579 
finishUnarchiving method 2-41, 2-199, 2-395 
finishUnarchiving: method 2-210 
firstPage method 2-469 
firstResponder method 2-705 
firstTextBlock method 2-579 
firstVisibleColumn method 2-330 
flagsChanged: method 2-485 
floatValue method 2-67, 2-129, 2-150, 2-185, 
2-504, 2-532 

HoatValueAt: method 2-229 
flushgraphics operator 4-16 
flush Window method 2-705 
flushWindowIfNeeded method 2-705 
focus View method 2-82 
Font class 

constants 2-203 
datatypes 2-203 
specification 2-195 

font method 2-108, 2-150, 2-185, 2-277, 2-461, 
2-579 

FontManager class 
constants 2-215 
data types 2-215 
specification 2-205 
fontNum method 2-200 
FontPanel class 
constants 2-223 
specification 2-217 
Form class 

specification 2-225 
FormCell class 

specification 2-235 
forward:: 2-42 
frameAngle method 2-660 
framebuffer operator 4-17 
free method 2-15, 2-22, 2-29, 2-35, 2-43, 2-56, 
2-60, 2-83, 2-108, 2-129, 2-150, 2-171, 2-185, 
2-200, 2-237, 2-249, 2-277, 2-314,2-330, 2-350, 
2-382, 2-395, 2-419, 2-435, 2-440, 2-456, 2-469, 
2-480, 2-495, 2-542, 2-579, 2-661, 2-706 
freeGlobally method 2-456 
freeGState method 2-661 
freeKeys:values: 2-15 
freeObjects method 2-15, 2-22, 2-60 
frontwindow operator 4-17 
functions See C functions 
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getBoundingBox: method 2-382 
getBounds: method 2-661 
getButtonFrame: method 2-462 
getCellFrame:at:: 2-277 
getCeliSize: method 2-277 
getContentRect:forFrameRect:style: 2-689 
getContentSize: method 2-513 
getContentSize:forFrameSize:horizScroller: 

vertScroller:borderType: 2-511 
getDataPlanes: method 2-314 
getDefaultFont method 2-569 
getDocRect: method 2-171 
getDocVisibleRect: method 2-172, 2-513 
getDrawRect: method 2-130, 2-150 
getEPSrlength: 2-383 
getE ventStatus: sound S tatus: e ventS tream: 
soundfile: 2-419 

getFamily:traits:weight:size:ofFont: 2-210 
getFieldEditorrfor: 2-706 
getFileIconFor:TIFF:TIFFLength:ok 

2-542 

getFileIconFor:TIFF:TIFFLength:ok: 2-249 
getFileInfoFor:app:type:ilk:ok 

2-543 

getFilelnfoFor:app:type:ilk:ok: 2-249 
getFontMenu: method 2-210 
getFontPanel: method 2-211 
getFrame: method 2-661, 2-706 
getFramerandScreen: 2-706 
getFrame:ofColumn: 2-330 
getFrame:ofInsideOfColumn: 2-331 
getFrameRect:forContentRect:style: 2-690 
getFrameSize:forContentSize:horizScroller: 

vertScrollenborderTtype: 2-512 
getlconRect: method 2-130,2-150 
getlmage:rect: 2-395 
getlntercell: method 2-277 
getKnobRect:flipped: 2-533 
getLoadedCelIAtRow:inColumn: 2-331 
getLocation: for Submenu: 2-299 
getLocation:ofCell: 2-579 
getLocation :ofView: 2-580 
getMarginLeft:right:top:bottom: 2-469, 2-580 
getMaxSize: method 2-580 
getMinSize: method 2-580 
getMinWidth:minHeight:maxWidth: 

maxHeight: 2-580 
getMouseLocation: method 2-707 
getNextEvent: method 2-83 
getNextEvent:waitFor:threshold: 2-83 
getNumRows:numCols: 2-277 
getOffsets: method 2-108 


getParagraph: start: end: rect: 2-581 
getParameter: method 2-130, 2-150 
getPath:toColumn: 2-331 
getPeriodicDelay:andInterval: 2-116, 2-131, 
2-151 

getRectrforPage: 2-661,2-707 
getRow:andCoI:forPoint: 2-278 
getRow:andCol:ofCell: 2-278 
getScreens:count: 2-84 
getScreenSize: method 2-84 
getSel:: 2-581 

getSize: method 2-395, 2-413 
getSubstring:start:length: 2-581 
getTit!eFrame:ofColumn: 2-331 
getTitleFromPreviousColumn: method 2-332 
getTitleRect: method 2-131,2-151 
getVisibleRect: method 2-662 
getWidthOf: method 2-200 
getWindow:andRect: 2-350 
getWindowNumbers:count: 2-84 
gState method 2-662, 2-707 

has Alpha method 2-413 
hasDynamicDepthLimit method 2-707 
hash method 2-43 
HashTable class 

specification 2-13 
hasMatrix method 2-200 
hasSubmenu method 2-304 
heightAdjustLimit method 2-662, 2-708 
hide: method 2-84 
hideCaret method 2-582 
hidecursor operator 4-17 
hideinstance operator 4-18 
hideLeftAndRightScrollButtons: method 2-332 
highlight: method 2-116, 2-504 
highlight:inView:lit: 2-131, 2-151, 2-347, 2-522, 
2-617 

highlightCellAt::lit: 2-278 
highlightsBy method 2-131 
hitPart method 2-504 
hitTest: method 2-663 
horizPagination method 2-469 
horizScroller method 2-514 
hostName method 2-84 

icon method 2-116,2-131,2-151 

iconEntered: at:: icon Window: iconX: icon Y: 

iconWidth:iconHeight:pathList: 2-250, 2-544 
iconExitedAt:: 2-251, 2-545 
iconMovedTo:: 2-252, 2-545 
iconPosition method 2-116, 2-132 
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iconReleasedAt::ok: 2-252, 2-545 
id data type 1-15 
ignoreMultiClick: method 2-185 
image method 2-116,2-132,2-371 
imageDidNotDraw:inRect: 2-409 
IMP data type 1-15 
incrementState method 2-152 
indexOf: method 2-22 
indexOfltem: method 2-462 
init method 2-16, 2-22, 2-29, 2-43, 2-56, 2-116, 
2-132, 2-152, 2-237, 2-253, 2-299, 2-304, 2-315, 
2-347, 2-351, 2-371, 2-376, 2-383, 2-396, 2-419, 
2-447, 2-462, 2-469, 2-522, 2-533, 2-545, 2-635, 
2-663, 2-708 

initContent: sty le: backing: button Mask: defer: 

2-448, 2-708 

initContent: style: backing: butt onMask: defer: 

screen: 2-710 
initCount: method 2-23 
initCount:elementSize:description: 2-57 
initData:fromRect: 2-315 
initData:pixelsWide:pixelsHigh:bitsPerSample: 
samplesPerPixel: has Alpha: isPlanar: 
colorSpace:bytesPerRow:bitsPerPixel: 2-316 
initDataPlanes:pixelsWide:pixelsHigh: 
bitsPer Sample: samplesPerPixel: has Alpha: 
isPlanar:colorSpace:bytesPerRow: 
bitsPerPixel: 2-317 
initDrawMethod:inObject: 2-376 
initFrame method 2-229, 2-332 
initFrame: method 2-108, 2-117, 2-172, 2-185, 
2-278, 2-366, 2-426, 2-505, 2-514, 2-526, 2-582, 
2-628, 2-663 

initFrame:icon:tag:target:action:key:enabled: 

2-117 

initFrame: mode: cellClass: numRows: numCols: 

2-279 

initFrame:mode:prototype:numRows: 
numCols: 2-279 

initFrame:text:alignment: 2-582 
initFrame:title:tag:target:action:key:enabled: 

2-117 

initFromFile: method 2-319, 2-383, 2-396 
initFromlmage: method 2-372 
initFromlmagerrect: 2-396 
initFromSection: method 2-320, 2-383, 2-397 
initFromStream: method 2-320, 2-384, 2-397 
initFromWindowrrect: 2-351 
initgraphics operator 4-18 
initGState method 2-663 
initialize method 2-35, 2-76, 2-169, 2-197, 2-247, 
2-272, 2-569 

initlconCell: method 2-132, 2-152 
initKeyDesc: method 2-16 


initKeyDescrvalueDesc: 2-16 
initKeyDesc:valueDescrcapacity: 2-16 
initSize: method 2-398 
initState method 2-17 
initStreamState method 2-60 
initTextCell method 2-304, 2-523 
initTextCell: method 2-132, 2-152, 2-237, 2-347, 
2-635 

initTitle: method 2-299 

insert:at: 2-57 

insertColAt: method 2-280 

insertEntry:at: 2-229 

insertEntry:at:tag:target:action: 2-229 

insertltem:at: 2-462 

insertKey:value: 2-17 

insertObject:at: 2-23 

insertRowAt: method 2-280 

insertStreamKey:value: 2-61 

instanceMethodFor: method 2-36 

instancesRespondTo: method 2-36 

intValue method 2-68, 2-133, 2-152, 2-185, 2-533 

intValueAt: method 2-230 

invalidate:: 2-664 

invalidateCursorRectsForView: method 2-710 
isActive method 2-85, 2-367 
isAllPages method 2-470 
isAutodisplay method 2-664 
isBackgroundTransparent method 2-280, 2-628 
isBezeled method 2-152, 2-628 
isBordered method 2-118, 2-133, 2-153, 2-628 
isCacheDepthBounded method 2-398 
isCellBackgroundTransparent method 2-280 
isColorMatchPreferred method 2-398 
isContinuous method 2-153, 2-186, 2-533 
isDataRetained method 2-398 
isDescendantOf: method 2-664 
isDisplayEnabled method 2-710 
isDocEdited method 2-710 
isEditable method 2-153, 2-583,2-628 
isEnabled method 2-153, 2-186, 2-211, 2-220 
isEntryAcceptable: method 2-153 
isEPSUsedOnResolutionMismatch method 2-399 
isEqual: method 2-23, 2-45, 2-57 
isExcludedFromWindowsMenu method 2-711 
isFlipped method 2-399, 2-664 
isFloatingPanel method 2-448 
isFocusView method 2-665 
isFontPanelEnabled method 2-583 
isHidden method 2-85 
isHighlighted method 2-153 
isHorizCentered method 2-470 
isHorizResizable method 2-583 
isjournalable method 2-85 
isKey: method 2-17 
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isKeyWindow method 2-711 
isKindOf: method 2-45 
isKindOfGivenName: method 2-46 
isLeaf method 2-347, 2-523 
isLoaded method 2-348 
isMain Window method 2-711 
isManualFeed method 2-470 
isMatchedOnMultipleResolution method 2-399 
isMemberOf: method 2-46 
isMemberOfGivenName: method 2-46 
isMonoFont method 2-583 
isMultiple method 2-211 
isOneShot method 2-711 
isOpaque method 2-133, 2-154, 2-237, 2-348, 
2-523, 2-533, 2-635, 2-665 
isPlanar method 2-320 
isRetainedWhileDrawing: method 2-584 
isRotatedFromBase method 2-665 
isRotatedOrScaledFromBase method 2-665 
isRulerVisible: method 2-584 
isRunning method 2-85 
isScalable method 2-399 
isScrollable method 2-154 
isSelectable method 2-154, 2-584, 2-628 
isTitled method 2-332, 2-333 
isTransparent method 2-118, 2-133 
isUnique method 2-400 
isVertCentered method 2-470 
isVertResizable method 2-584 
isVisible method 2-711 
itemList method 2-300 
Ivar data type 1-16 

journalerDidEnd: method 2-421 
journalerDidUserAbort: method 2-421 

keyDown method 2-333 
keyDown: method 2-448, 2-485, 2-584 
keyEquivalent method 2-118, 2-133, 2-154 
keyUp: method 2-485 
keyWindow method 2-85 
knowsPagesFirst:last: 2-665, 2-712 

lastColumn method 2-333 
lastObject method 2-23 
lastPage method 2-470 
lastRepresentation method 2-400 
lastVisibleColumn method 2-333 
launchProgram:ok: 2-253,2-546 
lineFromPosition: method 2-585 
lineHeight method 2-585 
List class 

specification 2-19 


Listener class 

specification 2-241 
listener method 2-419 
listenPort method 2-253 
loadColumnZero method 2-333 
IoadFromStream: method 2-400 
IoadNibFilerowner: 2-85 
loadNibFile:owner:withNames: 2-86 
loadNibFile:owner:withNames:fromZone: 2-86 
loadNibSection:owner: 2-86 
loadNibSection:owner:withNames: 2-87 
loadNibSection:owner:withNames: 

fromHeader: 2-87 

loadNibSection:owner:withNames:fromHeader: 

fromZone: 2-87 

loadNibSection:owner:withNames:fromZone: 

2-88 

lockFocus method 2-401,2-666 
lockFocusOn: method 2-401 

machportdevice operator 4-18 
mainMenu method 2-88 
mainScreen method 2-88 
main Window method 2-88 
makeCellAt:: 2-280 
makeFirstResponder: method 2-712 
makeKeyAndOrderFront: method 2-713 
makeKey Window method 2-713 
makeObjectsPerform: method 2-24 
makeObjectsPerformrwith: 2-24 
makeWindowsPerform:inOrder: 2-89 
marg_getRef() 3-154 
marg_getValue() 3-154 
marg_setValue() 3-154 
masterJournaler method 2-89 
Matrix class 

specification 2-267 
matrix method 2-200 
matrixInColumn: method 2-333 
max Value method 2-526, 2-533 
maxVisibleColumns method 2-334 
Menu Cell class 

specification 2-303 
Menu class 

specification 2-295 
menuZone: method 2-297 
messageReceived: method 2-253 
Method data type 1-16 
method_getArgumentInfo() 3-155 
method_getNumberOfArguments!) 3-155 
method_getSizeOfArguments!) 3-155 
methodFor: method 2-46 
metrics method 2-201 
minColumnWidth method 2-334 
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minFrameWidth:forStyle:buttonMask: 2-690 
miniaturize: method 2-713 
miniwindowlcon method 2-713 
min Value method 2-526, 2-534 
modifyFont: method 2-211 
modify Font ViaPanel: method 2-212 
Module data type 1-16 
mouse:inRect: 2-666 

mouseDown: method 2-186, 2-281, 2-300, 2-334, 
2-367, 2-426, 2-485, 2-505, 2-527, 2-585, 2-629 
mouseDownFlags method 2-154, 2-186, 2-281 
mouseDragged: method 2-485 
mouseEntered: method 2-372, 2-485 
mouseExited: method 2-372, 2-485 
mouseMoved: method 2-486 
mouseUp: method 2-486 
moveBy:: 2-666 
moveCaret: method 2-585 
moveTo:: 2-172,2-585,2-666,2-714 
moveTo::screen: 2-714 
moveTopLeftTo:: 2-300,2-714 
moveTopLeftTo::screen: 2-714 
movewindow operator 4-22 
msgCalc: method 2-254, 2-546 
msgCopyAsType:ok: 2-254, 2-546 
msgCutAsType:ok: 2-254, 2-546 
msgDirectory:ok: 2-254, 2-546 
msgFile:ok: 2-255, 2-547 
msgPaste: method 2-255, 2-547 
msgPosition:posType:ok: 2-255, 2-547 
msgPrint:ok: 2-256, 2-547 
msgQuit: method 2-256, 2-547 
msgSelection:length:asType:ok: 2-256, 2-548 
msgSetPosition: posType: andSelect 
ok: 2-256 

msgSetPosition:posType:andSelect:ok: 2-548 
msgVersion:ok: 2-257, 2-548 

name method 2-47, 2-201, 2-402, 2-456 
needsDisplay method 2-667 
new method 2-37,2-60,2-77,2-207,2-220,2-434, 
2-439, 2-454, 2-480 
newColorMask: method 2-357 
ne wContent: sty le: backing: buttonMask: defer: 

2-220, 2-356, 2-435, 2-440, 2-480, 2-493 
newContent:style:backing:buttonMask:defer: 

colorMask: 2-357 
newFont:size: 2-197 
newFont:size:matrix: 2-198 
newFont:size:style:matrix: 2-198 
newinstance operator 4-22 
newKeyDesc: method 2-60 
newListFromFile: method 2-310, 2-380 
newListFromFile:zone: 2-310, 2-380 


newListFromSection: method 2-310, 2-380 
newListFromSection:zone: 2-311, 2-381 
newListFromStream: method 2-311, 2-381 
newListFromStream:zone: 2-311, 2-381 
newName: method 2-454 
nextrelease operator 4-22 
nextResponder method 2-486 
nextState:key:value: 2-17 
NeXTStep functions 3-3 
NextStepEncoding operator 4-23 
nextStreamState:key:value: 2-61 
noResponderFor: method 2-486 
notify Ancestor WhenFrameChanged: method 
2-667 

notifyToInitGState: method 2-667 
notifyWhenFIipped: method 2-667 
notlmplemented: method 2-47 
numColors method 2-413 
numPlanes method 2-321 
numVisibleColumns method 2-334 
NX Color Panel class 
specification 2-353 
NX_ADDRESS() 3-134 
NX_ASSERT() 3-134 
NX_EVENTCODEMASK() 3-135 
NX_FREE() 3-136 
NX_HEIGHT() 3-139 
NX_MALLOC() 3-136 
NX_MAXX() 3-139 
NX_MAXY() 3-139 
NX_MIDX() 3-139 
NX_MIDY() 3-139 
NX_PSDEBUG 3-137 
NX_RAISE() 3-137 
NX_REALLOC() 3-136 
NX_RERAISE() 3-137 
NX_VALRETURN() 3-137 
NX_VOIDRETURN 3-137 
NX_WIDTH() 3-139 
NX_X() 3-139 
NX_Y() 3-139 

NX_ZONEMALLOC() 3-140 
NX_ZONEREALLOC() 3-140 
NXAIlocErrorDataO 3-23 
NXAlphaComponentO 3-103 
NXAppkitErrorTokens data type 1-16 
NXAsciiPboardType 5-3 
NXAtEOSO 3-114 
NX Atom data type 1-17 
NXAttachPopUpList() 3-23 
NXBeepO 3-24 
NXBeginTimerO 3-24 
NXBitmapImageRep class 
specification 2-307 
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NXBlackComponentO 3-103 
NXBlueComponentO 3-103 
NXBPSFromDepthO 3-30 
NXBrightnessComponentO 3-103 
NXBrowser class 

specification 2-323 
NXBrowserCell class 
specification 2-345 
NXCachedlmageRep class 
specification 2-349 
NXChangeAlphaComponentO 3-26 
NXChangeBlackComponent() 3-26 
NXChangeBlueComponent() 3-26 
NXChangeBrightnessComponent() 3-26 
NXChangeBuffer() 3-120 
NXChangeCyanComponentO 3-26 
NXChangeGrayComponent() 3-26 
NXChangeGreenComponent() 3-26 
NXChangeHueComponent() 3-26 
NXChangeMagentaComponent() 3-26 
NXChangeRedComponent() 3-26 
NXChangeSaturationComponentO 3-26 
NXChangeYellowComponent() 3-26 
NXCharMetrics data type 1-17 
NXChunk data type 1-17 
NXChunkCopyO 3-27 
NXChunkGrow() 3-27 
NXChunkMalIoc() 3-27 
NXChunkReallocO 3-27 
NXChunkZoneCopyO 3-27 
NXChunkZoneGrow() 3-27 
NXChunkZoneMallocO 3-27 
NXChunkZoneRealloc() 3-27 
NXClose() 3-29 
NXCloseMemoryO 3-77 
NXCloseTypedStream() 3-79 
NXColor data type 1-17 
NXColorSpace data type 1-18 
NXColorSpaceFromDepthO 3-30 
NXColorWell class 
specification 2-363 
NXCompleteFilename() 3-32 
NXCompositeChar data type 1-18 
NXCompositeCharPart data type 1-18 
NXContainsRectO 3-74 
NXConvertCMYKAToColorO 3-35 
NXConvertCMYKToColorO 3-35 
NXConvertColorToCMYK() 3-33 
NXConvertColorToCMYKA() 3-33 
NXConvertColorToGrayO 3-33 
NXConvertColorToGrayAlpha() 3-33 
NXConvertColorToHSB() 3-33 
NXConvertColorToHSBAO 3-33 
NXConvertColorToRGBO 3-33 


NXConvertColorToRGBAO 3-33 
NXConvertGlobalToWinNum () 3-36 
NXConvertGrayAlphaToColor() 3-35 
NXConvertGrayToColor() 3-35 
NXConvertHSBAToColor() 3-35 
NXConvertHSBToColor() 3-35 
NXConvertRGBAToColor() 3-35 
NXConvertRGBToColor() 3-35 
NXConvertWinNumToGlobalO 3-36 
NXCoord data type 1-18 
NXCopyBits() 3-37 
NXCopyCurrentGStateO 3-115 
NXCopyHashTableO 3-41 
NXCopyInputData() 3-38 
NXCopyOutputData() 3-38 
NXCopyStringBuffer() 3-128 
NXCopyStringBufferFromZone() 3-128 
NXCountHashTable() 3-62 
NXCountWindowsO 3-40 
NXCreateChildZoneO 3-132 
NXCreateHashTable() 3-41 
NXCreateHashTabIeFromZone() 3-41 
NXCreatePopUpListButton() 3-23 
NXCreateZoneO 3-132 
NXCursor class 

specification 2-369 
NXCustomlmageRep class 
specification 2-375 
NXCyanComponentO 3-103 
NXDefaultExceptionRaiser() 3-44 
NXDefaultMallocZone() 3-132 
NXDefauItRead() 3-120 
NXDefaultStringOrderTable() 3-80 
NXDefaultsVector data type 1-19 
NXDefaultTopLeveIErrorHandler() 3-46 
NXDefaultWriteO 3-120 
NXDestroyZoneO 3-132 
NXDivideRect() 3-116 
NXDrawALine() 3-113 
NXDrawButton() 3-47 
NXDrawGrayBezel() 3-47 
NXDrawGroove() 3-47 
NXDrawTiledRects() 3-47 
NXDrawWhiteBezel() 3-47 
NXEditorFilter() 3-52 
NXEmptyRect() 3-74 
NXEncodedLigature data type 1-19 
NXEndOfTypedStream() 3-50 
NXEndTimer() 3-24 
NXEPSImageRep class 
specification 2-379 
NXEqualColor() 3-50 
NXEqualRect() 3-74 
NXEraseRect() 3-102 
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NXErrorReporter data type 1-19 
NXEvent data type 1-19 
NXEventData data type 1-20 
NXExceptionRaiser data type 1-20 
NXFieldFilterO 3-52 
NXFUenamePboardType 5-6 
NXFilePathSearch() 3-53 
NXFill() 3-120 
NXFindPaperSizeQ 3-54 
NXFlushO 3-55 
NXFlushTypedStream() 3-55 
NXFontMetrics data type 1-21 
NXFontPboardType 5-6 
NXFrameRect() 3-47 
NXFrameRectWithWidth() 3-47 
NXFreeAlertPanel() 3-111 
NXFreeHashTableO 3-41 
NXFreeObjectBuffer() 3-94 
NXGetAlertPanel() 3-111 
NXGetBestDepthO 3-30 
NXGetc(') 3-87 
NXGetDefaultValueO 3-104 
NXGetExceptionRaiser() 3-44 
NXGetMemoryl^ufferO 3-77 
NXGetNamedObject() 3-57 
NXGetObjectNameQ 3-57 
NXGetOrPeekEvent() 3-58 
NXGetTempFilename() 3-60 
NXGetTIFFInfo() 3-97 
NXGetTypedStreamZone() 3-60 
NXGetUncaughtExceptionHandler() 3-119 
NXGetWindowServerMemory () 3-61 
NXGrayComponent() 3-103 
NXGreenComponentO 3-103 
NXHandler data type 1-22 
NXHashGetO 3-62 
NXHashlnsertO 3-62 
NXHashInsertIfAbsent() 3-62 
NXHashMember() 3-62 
NXHashRemoveO 3-62 
NXHashState data type 1-22 
NXHashTablePrototype datatype 1-22 
NXHighlightRectO 3-102 
NXHomeDirectoryO 3-65 
NXHueComponentO 3-103 
NXImage class 

specification 2-385 
NXImageBitmapO 3-65 
NXImagelnfo data type 1-23 
NXImageRep class 
specification 2-411 
NXInitHashState() 3-62 
NXInsetRect() 3-116 
NXIntegralRect() 3-116 


NXIntersectionRect() 3-127 
NXIntersectsRectO 3-74 
NXIsAlNum() 3-70 
NXIsAlpha() 3-70 
NXIsAscii() 3-70 
NXIsCntrK) 3-70 
NXIsDigitO 3-70 
NXIsGraph() 3-70 
NXIsLower() 3-70 
NXIsPrintO 3-70 
NXIsPunct() 3-70 

NXIsServicesMenuItemEnabled() 3-118 
NXIsSpace() 3-70 
NXIsUpper() 3-70 
NXIsXDigitO 3-70 
NXJoumaler class 
constants 2-422 
data types 2-422 
specification 2-417 
NXJournalMouseO 3-72 
NXKemPair data type 1-23 
NXKemXPair data type 1-23 
NXLigature data type 1-23 
NXLogError() 3-73 
NXMagentaComponentO 3-103 
NXMallocCheck() 3-132 
NXMapFileO 3-77 
NXMergeZoneO 3-132 
NXMouselnRectO 3-74 
NXNameObject() 3-57 
NXNameZone() 3-132 
NXNextHashStateO 3-62 
NXNoEffectFree() 3-41 
NXNumberOfColorComponentsO 3-30 
NXOffsetRect() 3-116 
NXOpenFileO 3-76 
NXOpenMemoryO 3-77 
NXOpenPort() 3-76 
NXOpenTypedStream() 3-79 
NXOpenTypedStreamForFile() 3-79 
NXOrderStringsO 3-80 
NXPingQ 3-82 
NXPoint data type 1-24 
NXPointlnRectO 3-74 
NXPortFromName() 3-85 
NXPortNameLookupO 3-85 
NXPostScriptPboardType 5-4 
NXPrintfO 3-87 
NXPrintfProc data type 1-24 
NXPtrHash() 3-41 
NXPtrlsEqualO 3-41 
NXPutcO 3-87 
NXRead() 3-89 
NXReadArrayO 3-90 
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NXReadBitmapO 3-65 
NXReadColor() 3-91 
NXReadDefault() 3-104 
NXReadObjectO 3-92 
NXReadObjectFromBuffer() 3-94 
NXReadObjectFromBufferWithZone() 3-94 
NXReadPoint() 3-96 
NXReadRect() 3-96 
NXReadSize() 3-96 
NXReadTIFF() 3-97 
NXReadType() 3-98 
NXReadTypes() 3 98 
NXReadWordTableO 3-100 
NXReallyFreeO 3-41 
NXRect data type 1-24 
NXRectClipO 3-102 
NXRectClipList() 3-102 
NXRectFill() 3-102 
NXRectFillListO 3-102 
NXRectFillListWithGrays() 3-102 
NXRedComponentO 3-103 
NXRegisterDefaults() 3-104 
NXRegisterErrorReporter() 3-108 
NXRegisterPrintfProc() 3-109 
NXRemoteMethodFromSelO 3-110 
NXRemoveDefault() 3-104 
NXRemoveErrorReporter() 3-108 
NXReportError() 3-108 
NXResetErrorData() 3-23 
NXResetUserAbort() 3-130 
NXResponsibleDelegate() 3-110 
NXRTFPboardType 5-5 
NXRulerPboardType 5-7 
NXRunAlertPanel() 3-111 
NXSaturationComponent() 3-103 
NXSaveToFileO 3-77 
NXScanALineO 3-113 
NXScanf() 3-87 
NXScreen data type 1-24 
NXSeek() 3-114 
NXSetColor() 3-115 
NXSetDefauItO 3-104 
NXSetDefaultsUser() 3-104 
NXSetExceptionRaiser() 3-44 
NXSetGStateO 3-115 
NXSetRectO 3-116 

NXSetServicesMenuItemEnabled() 3-118 
NXSetTopLevelErrorHandler() 3-46 
NXSetUncaughtExceptionHandler() 3-119 
NXSize data type 1-24 
NXSizeBitmapO 3-65 
NXSoundPboardType 5-6 
NXSplitView class 
specification 2-423 


NXStream data type 1-25 
NXStreamCreateO 3-120 
NXStreamCreateFromZone() 3-120 
NXStreamDestroyO 3-120 
NXStreamErrors data type 1-25 
NXStringTable class 
specification 2-27 
NXStrlsEqualO 3-41 
NXSystemVersionO 3-122 
NXTabularTextPboardType 5-6 
NXTellO 3-114 
NXTextFontlnfoO 3 122 
NXTIFFInfo data type 1-25 
NXTIFFPboardType 5-4 
NXToAscii() 3-123 
NXToLower() 3-123 
NXTopLevelErrorHandler data type 1-26 
NXTopLevelErrorHandler() 3-46 
NXToUpper() 3-123 
NXTrackingTimer data type 1-26 
NXTrackKem data type 1-26 
NXTypedStream data type 1-26 
NXTvpedStreamClass Version!) 3-126 
NXUncaughtExceptionHandler data type 1-26 
NXUngetc 3-87 
NXUnionRectO 3-127 
NXUniqueStringO 3-128 
NXUniqueStringNoCopyO 3-128 
NXUniqueStringWithLength() 3-128 
NXUnnameObject() 3-57 
NXUpdateDefaultO 3-104 
NXUpdateDefaults() 3-104 
NXUpdateDynamicServicesO 3-130 
NXUserAborted() 3-130 
NXUserNameO 3-65 
NXVPrintf() 3-87 
NXVScanf() 3-87 
NXWindowList() 3-40 
NXWriteO 3-89 
NXWriteArrayO 3-90 
NXWriteColor() 3-91 
NXWriteDefaultO 3-104 
NXWriteDefaultsO 3-104 
NXWriteObject() 3-92 
NXWriteObjectReference() 3-92 
NXWritePoint() 3-96 
NXWriteRectO 3-96 
NXWriteRootObject() 3-92 
NXWriteRootObjectToBiiffer() 3-94 
NXWriteSizeO 3-96 
NXWriteTIFFO 3-97 
NXWriteiypeO 3-98 
NXWriteTypesO 3-98 
NX Write WordTable() 3-100 
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NXYellowComponentO 3-103 
NXZoneCalloc() 3-132 
NXZoneFreeO 3-132 
NXZoneFromPtrO 3-132 
NXZoneMalloc() 3-132 
NXZonePtrlnfoO 3-132 
NXZoneRealloc() 3-132 
NZSetTypedStreamZone() 3-60 

objc_addClass() 3-156 
objc_getClass() 3-156 
°bjc_getClasses() 3-156 
objc_getMetaClass() 3-156 
objc_getModules() 3-156 
objc_loadModules() 3-157 
objc_msgSend() 3-158 
objc_msgSendSuper() 3-158 
objc_msgSendv() 3-158 
objc_unloadModules() 3-157 
Object class 

specification 2-31 
Object Methods class 
specification 2-429 
object_copy() 3-159 
object_copyFromZone() 3-159 
object_dispose() 3-159 
object_getClassName() 3-161 
object_getIndexedIvars() 3-161 
object_getInstanceVariab!e() 3-162 
object_reaIloc() 3-159 
object_reallocFromZone() 3-159 
object_setInstanceVariableO 3-162 
objectAt: method 2-24 
obscurecursor operator 4-23 
ok: method 2-495 
opaqueAncestor method 2-668 
openFile:ok: 2-89, 2-257, 2-548 
OpenPanel class 

specification 2-433 
openSpoolFile method 2-714 
openSpoolFile: method 2-668 
openTempFile:ok: 2-89, 2-258, 2-549 
orderBack: method 2-715 
orderFront: method 2-715 
orderFrontColorPanel: method 2-90 
orderFrontFontPanel: method 2-212 
orderOut: method 2-715 
orderwindow operator 4-24 
orderWindow:re!ativeTo: 2-221, 2-716 
orientation method 2-470 
osname operator 4-25 
ostype operator 4-25 


outputFile method 2-470 
overstrikeDiacriticals method 2-586 

PageLayout class 
constants 2-444 
specification 2-437 
pageOrder method 2-471 
pagesPerSheet method 2-471 
Panel class 

specification 2-445 
panel:filterFile:inDirectory: 2-497 
panelConvertFont: method 2-221 
panelValidateFilenames: method 2-497 
paperRect method 2-471 
paperType method 2-471 
paste: method 2-586 
Pasteboard class 

specification 2-451 

pasteboard:provideData: method 2-458 
pasteFont: method 2-586 
pasteRuler: method 2-587 
peekAndGetNextEvent: method 2-90 
peekNextEvent:into: 2-90 
peekNextEvent:into:waitForthreshold: 2-90 
perform: method 2-48 
perform:with: 2-48 

perform:with:afterDelay:cancelPrevious: 2-429 
perform:with:with: 2-49 
performClick: method 2-118,2-133 
performClose: method 2-716 
performKeyEquivalent: method 2-118, 2-281, 
2-486, 2-668 

performMiniaturize: method 2-716 
performRemoteMethod: method 2-549 
performRemoteMethod: paramList: 2-25 8 
performRemoteMethod:with:length: 2-549 
performv:: 2-49 
pickedAHPages: method 2-481 
pickedButton: method 2-441, 2-481 
pickedLayout: method 2-441 
pickedOrientation: method 2-441 
pickedPaperSize: method 2-441 
pickedUnits: method 2-442 
pixelsHigh method 2-414 
pixels Wide method 2-414 
placePrintRect:offset: 2-669, 2-716 
placewindow operator 4-26 
place Window: method 2-717 
placeWindow:screen method 2-717 
place Window AndDisplay: method 2-717 
playsound operator 4-27 
pointSize method 2-201 
pop method 2-371,2-372 
popUp: method 2-462 


Index-13 



PopUpList class 

specification 2-459 
portName method 2-258 
pose As: method 2-38 
positionFromLine: method 2-587 
posteventbycontext operator 4-27 
PostScript 

client library functions 3-3 
operators 4-1 

single-operator functions 3-141 
postSelSmartTable method 2-587 
powerOff: method 2-91, 2-103 
powerOffTn:andSave: 2-91, 2-259, 2-550 
prefersTrackingUntilMouseUp 2-530 
prefersTrackingUntilMouseUp method 2-146 
prepareGState method 2-384 
preSelSmartTable method 2-588 
printerHost method 2-471 
printerName method 2-471 
printerType method 2-471 
Printlnfo class 

specification 2-465 
printlnfo method 2-91 
PrintPanel class 

specification 2-477 
printPSCode: method 2-669,2-717 
priority method 2-259 
prototype method 2-282 
“PS” single-operator functions 3-141 
pswrap 3-141 
push method 2-373 
putCell:at:: 2-282 

rawScroll: method 2-172 
read: method 2-18, 2-24, 2-50, 2-57, 2-61, 2-68, 
2-109, 2-133, 2-154, 2-173, 2-186, 2-201, 2-238, 
2-259, 2-282, 2-300, 2-304, 2-321, 2-351, 2-373, 
2-376, 2-384, 2-402, 2-414, 2-471, 2-486, 2-505, 
2-514, 2-534, 2-550, 2-588, 2-629, 2-636, 2-669, 
2-718 

readFromFile: method 2-29 
readFromStream: method 2-29 
readimage operator 4-28 
readMetrics: method 2-201 
readPrintlnfo method 2-442, 2-481 
readRichText: method 2-588 
readRichText:atPosition: 2-588 
readRichText:forView: 2-617 
readSelectionFromPasteboard: method 2-430, 
2-588 

readText: method 2-589 
readType: data: length: 2-456 
recache method 2-402 
recordDevice method 2-420 


reenableDisplay method 2-718 
reenableFlushWindow method 2-718 
reflectScroll: method 2-177, 2-334,2-514 
registerDirective:forClass: 2-569 
registerServicesMenuSendTy pes: 

andReturnTypes: 2-91 
registerWindow:toPort: 2-259, 2-550 
reloadColumn: method 2-335 
remoteMethodFor: method 2-260 
removeAt: method 2-57 
removeColAt:andFree: 2-282 
removeCursorRect:cursor: 2-669 
removeCursorRect:cursor:forView: 2-718 
removeEntryAt: 2-230 
removeFontTrait: method 2-212 
removeFromEventMask: method 2-718 
removeFromSuperview method 2-670 
removeltem: method 2-462 
removeltemAt: method 2-463 
removeKey: method 2-18 
removeLastElement method 2-58 
removeLastObject method 2-24 
removeObject: method 2-25 
removeObjectAt: method 2-25 
removePort method 2-260 
removeRepresentation: method 2-402 
removeRowAt:andFree: 2-282 
removeStreamKey: method 2-61 
removeWindowsItem: method 2-92 
renderbands operator 4-29 
renewFont:size:style:text:frame:tag: 2-589 
renewFont:text:frame:tag: 2-589 
renewGState method 2-670 
renewRows:cols: 2-283 
renewRuns:text:frame:tag: 2-590 
replace:at: 2-58 
replaceObject:with: 2-25 
replaceObjectAt:with: 2-25 
replaceSel: method 2-590 
replaceSel:length: 2-590 
replaceSel:length:runs: 2-590 
replaceSelWithCell: method 2-591 
replaceSelWithRichText: method 2-591 
repIaceSelWithView: method 2-591 
replaceSubview:with: 2-670 
replyPort method 2-92,2-551 
replyTimeout method 2-551 
representationList method 2-402 
requiredFileType method 2-495 
reset method 2-348 

resetCursorRect:inView: 2-155, 2-238 
resetCursorRects method 2-173, 2-187, 2-283, 
2-670, 2-719 

resignActiveApp method 2-92 
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resignFirstResponder method 2-487, 2-591 
resignKeyWindow method 2-592, 2-719 
resignMainWindow method 2-719 
resizeSubviews: method 2-426, 2-515, 2-671 
resizeText:: 2-592 
resolution method 2-472 
Responder class 

specification 2-483 
respondsTo: method 2-50 
reuseColumns: method 2-335 
revealcursor operator 4-29 
rightbuttondown operator 4-29 
rightMouseDown: method 2-92, 2-300, 2-487, 
2-720 

rightMouseDragged: method 2-487 
rightMouseUp: method 2-487 
rightstilldown operator 4-29 
rotate: method 2-173, 2-671 
rotateBy: method 2-671 
rotateTo: method 2-173, 2-671 
run method 2-92, 2-247 
runModal method 2-443, 2-481, 2-495 
runModalFor: method 2-93 
runModalForDirectory:file: 2-436, 2-495 
runModalForDirectory:file:types: 2-436 
runModalForTypes: method 2-436 
runModalSession: method 2-93 
runPageLayout: method 2-93 
run-time functions 3-148 

samplesPerPixel method 2-321 
SavePanel class 

specification 2-491 
scale:: 2-174,2-672 
scalingFactor method 2-472 
scanFunc method 2-592 
screen method 2-720 
screenChanged: method 2-720 
screenFont method 2-201 
screenlist operator 4-30 
screentobase operator 4-30 
screentocurrent operator 4-31 
scrollCellToVisible:: 2-283 
scrollClip:to: 2-177 
scrollColumnsLeftBy: method 2-335 
scrollColumnsRightBy: method 2-335 
scrolIColumnToVisible: method 2-335 
Scroller class 

constants 2-508 
specification 2-499 
scrollPoint: method 2-672 
scrollRect:by: 2-672 
scrollRectToVisible: method 2-672 
scrollSelToVisible method 2-592 


scrollUpOrDown: method 2-336 
Scroll View class 

specification 2-509 
SEL data type 1-27 
sel_getName() 3-163 
sel_getUid() 3-163 
sel_isMapped() 3-164 
select:inView:editor:delegate:start:length: 

2-155 

selectAll method 2-336 
selectAll: method 2-283, 2-592 
selectCell: method 2-283 
selectCellAt:: 2 284 
selectCellWithTag: method 2-284 
selectedCell method 2-187, 2-284 
selectedCol method 2-284 
selectedColumn method 2-336 
selectedlndex method 2-230 
selectedltem method 2-463 
selectedRow method 2-284 
selectedTag method 2-187 
selectError method 2-593 
SelectionCell class 
specification 2-521 
selectNull method 2-593 
selectorRPC :paramTypes: 2-551 
selectText: method 2-284, 2-495, 2-593, 2-629 
selectTextAt: method 2-230 
selectTextAt:: 2-285 
self method 2-50 
selFont method 2-213 
selGray method 2-593 
sendAction method 2-213, 2-285 
sendAction:to: 2-188, 2-285 
sendAction:to:forAlICells: 2-285 
sendAction:to:from: 2-94 
sendActionOn: 
method 2-155 

sendActionOn: method 2-188 
sendDoubleAction method 2-286 
sendEvent: method 2-94, 2-720 
sendOpenFileMsg:ok:andDeactivateSelf: 2-552 
sendOpenTempFileMsg:ok:andDeactivateSelf: 

2-552 

sendPort method 2-552 
sendTimeout method 2-553 
separateColumns: method 2-336 
servicesDelegate method 2-260 
servicesMenu method 2-94 
set method 2-202, 2-373 
setAccessoryView: method 2-221, 2-359, 2-443, 

2-482, 2-496 

setAction: method 2-68, 2-155,2-188,2-213, 

2-286, 2-336, 2-359, 2-367, 2-463,2-505 
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setAction:at: 2-230 
setAction:at:: 2-286 
setactiveapp operator 4-31 
setAlignment: method 2-68, 2-156, 2-188, 2-594 
setAllPages: method 2-472 
setalpha operator 4-31 
set Alpha: method 2-414 
setAltlcon: method 2-119,2-134 
setAltlmage: method 2-119,2-134 
setAltTitle: method 2-119,2-134 
setAppListener: method 2-94 
setAppSpeaker: method 2-95 
setArrowsPosition: method 2-506 
setAutodisplay: method 2-672 
setautofill operator 4-32 
setAutoresizeSubviews: method 2-426, 2-673 
setAutoscroll: method 2-286 
setAutosizeCells: method 2-286 
setAutosizing: method 2-673 
setAutoupdate: method 2-95, 2-300 
setAvailableCapacity: method 2-26, 2-58 
setBackgroundColor: method 2-174, 2-287, 
2-403, 2-515, 2-594, 2-629, 2-636, 2-720 
setBackgroundGray: method 2-174,2-287,2-515, 
2-595, 2-629, 2-636, 2-721 
setBackgroundTransparent: method 2-287, 
2-629, 2-635, 2-636 

setBecomeKeyOnlylfNeeded: method 2-449 
setBezeled: method 2-68, 2-156, 2-230, 2-629, 
2-636 

setBitsPerSample: method 2-414 
setBordered: method 2-68,2-119, 2-134, 2-156, 
2-230, 2-629 

setBorderType: method 2-109,2-515 
setBreakTable: method 2-595 
setCacheDepthBounded: method 2-403 
setCell: method 2-189 
setCellBackgroundColor: method 2-287 
setCellBackgroundGray: method 2-287 
setCellBackgroundTransparent: method 2-287 
setCellClass: method 2-115, 2-182, 2-227, 2-273, 
2-288, 2-337, 2-526, 2-627 
setCellPrototype: method 2-337 
setCellSize: method 2-288 
setCharCategoryTable: method 2-595 
setCharFilter: method 2-595 
setCharWrap: method 2-596 
setClickTable: method 2-596 
setClipping: method 2-673 
setColor: method 2-359, 2-367 
setColorMask: method 2-359 
setColorMatchPreferred: method 2-403 
setContentView: method 2-109, 2-721 
setContext: method 2-472 


setContinuous: method 2-156, 2-189, 2-359, 
2-367, 2-534 

setCopies: method 2-472 
setCopyOnScroll: method 2-174, 2-516 
setcursor operator 4-32 
setDataRetained: method 2-403 
setdefaultdepthlimit operator 4-33 
setDefaultFont: method 2-570 
setDelegate: method 2-95, 2-260, 2-337, 2-404, 
2-420, 2-427, 2-496, 2-553, 2-596, 2-721 
setDepthLimit: method 2-722 
setDescentLine: method 2-596 
setDirectory: method 2-496 
setDisplayOnScroll: method 2-175, 2-516 
setDocCursor: method 2-175, 2-516 
setDocEdited: method 2-722 
setDocView: method 2-175,2-516 
setDoubleAction: method 2-288, 2-337 
setDoubleValue: method 2-134, 2-156, 2-189, 
2-534 

setDoubleValue:at: 2-231 
setDrawFunc: method 2-596 
setDrawOrigin:: 2-175, 2-674 
setDrawRotation: method 2-176, 2-674 
setDrawSize:: 2-176, 2-674 
setDynamicDepthLimit: method 2-722 
setDynamicScrolling: method 2-517 
setEditable: method 2-157, 2-597, 2-630 
setEnabled: method 2-69, 2-157, 2-189, 2-214, 
2-222, 2-238, 2-288, 2-337, 2-368, 2-527, 2-630 
setEntryType: method 2-157 
setEntryWidth: method 2-231 
setEPSUsedOnResolutionMismatch: method 
2-404 

setErrorAction: method 2-288, 2-630 
seteventmask operator 4-34 
setEventMask: method 2-722 
setEventStatus:soundStatus:eventStream: 

soundfile: method 2-420 
setExcludedFromWindowsMenu: method 2-723 
setexposurecolor operator 4-35 
setFirstPage: method 2-472 
setFlipped: method 2-404, 2-674 
setFloatingPanel: method 2-449 
setFloatingPointFormat:left:right: 2-69, 2-158, 
2-190 

setFloatValue: method 2-135,2-158,2-189,2-506, 
2-534 

setFloat Value:: 2-506 
setFloatValue:at: 2-231 
setflushexposures operator 4-35 
setFont: method 2-69, 2-109,2-135, 2-158,2-190, 
2-231, 2-289, 2-463, 2-597 
setFont:paraStyle: 2-597 
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setFontPanelEnabled: method 2-597 
setFontPanelFactory: method 2-207 
setFrame: method 2-675 
setFrameFromContentFrame: method 2-109 
setFreeWhenClosed: method 2-723 
setHideOnDeactivate: method 2-724 
setHighlightsBy: method 2-135 
setHorizCentered: method 2-472 
setHorizPagination: method 2-473 
setHorizResizable: method 2-598 
setHorizScroller: method 2-517 
setHorizScrollerRequired: method 2-517 
setHotSpot: method 2-373 
setlcon: method 2-69, 2-119, 2-135, 2-158 
setIcon:at:: 2-289 
setIcon:position: 2-119 
setlconPosition: method 2-120, 2-136 
setlmage: method 2-120, 2-136, 2-374 
setinstance operator 4-35 
setlntercell: method 2-289 
setlnterline: method 2-231 
setlntValue: method 2-136, 2-159, 2-190, 2-534 
setIntValue:at: 2-231 
setltemList: method 2-301 
setjournalable: method 2-95 
setKeyEquivalent: method 2-120, 2-136 
setKeyEquivalentFont: method 2-137 
setKeyEquivalentFont:size: 2-137 
setLastColumn: method 2-338 
setLastPage: method 2-473 
setLeaf: method 2-348, 2-523 
setLineHeight:method 2-598 
setLineScroll: method 2-517 
setLoaded: method 2-348 
setLocation:ofCell: 2-598 
setMainMenu: method 2-95 
setManualFeed: method 2-473 
setMarginLeft:right:top:bottom: 2-473, 2-598 
setMatchedOnMultipleResolution: method 
2-404 

setMatrixClass: method 2-338 
setMaxSize: method 2-599 
setMaxValue: method 2-527, 2-534 
setMaxVisibleColumns: method 2-338 
setMenuZone method 2-297 
setMinColumnWidth: method 2-338 
setMiniwindowIcon: method 2-724 
setMinSize: method 2-599 
setMinValue: method 2-527, 2-535 
setMode: method 2-289, 2-360 
setMonoFont: method 2-599 
setmouse operator 4-36 
setName: method 2-405 
setNeedsDisplay: method 2-675 


setNextResponder: method 2-487 
setNextText: method 2-289, 2-630 
setNoWrap method 2-599 
setNumColors: method 2-415 
setNumSlots: method 2-58 
setOffsets:: 2-110 
setOneShot: method 2-724 
setOnMouseEntered: method 2-374 
setOnMouseExited: method 2-374 
setOpaque: method 2-675 
setOrientation:andAdjust: 2-473 
setOutputFile: method 2-474 
setOverstrikeDiacriticals: method 2-599 
setowner operator 4-36 
setPageOrder: method 2-474 
setPageScrolI: method 2-518 
setPagesPerSheet: method 2-474 
setPanelFont:isMultiple: 2-222 
setPaperRect:andAdjust: 2-474 
setPaperType: and Adjust: 2-474 
setParameter:to: 2-137, 2-159 
setParaStyle: method 2-600 
setPath: method 2-339 
setPathSeparator: method 2-339 
setpattern operator 4-36 
setPeriodicDelay:andInterval: 2-120, 2-137 
setPixelsHigh: method 2-415 
setPixelsWide: method 2-415 
setPostSelSmartTable: method 2-600 
setPreSelSmartTable: method 2-600 
setPreviousText: method 2-290, 2-630 
setPrinterHost: method 2-475 
setPrinterName: method 2-475 
setPrinterType: method 2-475 
setPrintlnfo: method 2-95 
setPriority: method 2-261 
setPrompt: method 2-496 
setPrototype: method 2-290 
setReaction: method 2-290 
setRecordDevice: method 2-421 
setReplyPort: method 2-553 
setReplyTimeout: method 2-554 
setRequiredFileType: method 2-496 
setResolution: method 2-475 
setRetainedWhileDrawing: method 2-600 
setScalable: method 2-405 
setScalingFactor: method 2-475 
setScanFunc: method 2-601 
setScrollable: method 2-159,2-291 
setSel:: 2-601 
setSelColor: method 2-601 
setSelectable: method 2-159, 2-601,2-630 
setSelFont: method 2-602 
setSelFont:isMultiple: 2-214 
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setSelFont:paraStyle: 2-602 
setSelFontFamily: method 2-602 
setSelFontSize: method 2-602 
setSelFontStyle: method 2-603 
setSelGray: method 2-603 
setSelProp:to: 2-604 
setsendexposed operator 4-37 
setSendPort: method 2-554 
setSendTimeout: method 2-554 
setServicesDelegate: method 2-262 
setServicesMenu: method 2-96 
setShowAlpha: method 2-360 
setShowsStateBy: method 2-138 
setSize: method 2-405, 2-415 
setSound: method 2-121, 2-138 
setState: method 2-121, 2-159 
setState:at:: 2-291 

setStringValue: method 2-69,2-138,2-160,2-190, 
2-535 

setStringValue:at: 2-231 
setStringValueNoCopy: method 2-138, 2-160, 
2-190 

setStringValueNoCopy:shouldFree: 2-70,2-160, 
2-190 

setStyle: method 2-202 
setSubmenurforltem: 2-301 
setTag: method 2-70, 2-160, 2-191, 2-605 
setTag:at: 2-232 
setTag:at:: 2-291 
setTag:target:action:at:: 2-291 
setTarget: method 2-70, 2-160, 2-191, 2-291, 
2-339, 2-360, 2-368, 2-463,2-506 
setTarget:at: 2-232 
setTarget:at:: 2-292 
setText: method 2-605 
setTextAlignment: method 2-232 
setText Attributes: method 2-161, 2-636 
setTextColor: meethod 2-631 
setTextColor: method 2-605, 2-637 
setTextDelegate: method 2-292, 2-631 
setTextFilter: method 2-605 
setTextFont: method 2-232 
setTextGray: method 2-606, 2-631 
setTextGray: metnhod 2-637 
setTimeout: method 2-263 
setTitle: method 2-110,2-121,2-138,2-238,2-496, 
2-724 

setTitle:at: 2-232 
setTitle:at:: 2-292 
setTit!e:ofColumn: 2-339 
setTitleAlignment: method 2-232, 2-238 
setTitleAsFilename: method 2-725 
setTitled: method 2-340 
setTitleFont: method 2-233, 2-238 


setTitleNoCopy: method 2-121, 2-139 
setTitlePosition: method 2-110 
setTitle Width: method 2-238 
settrackingrect operator 4-37 
setTrackingRect:inside:owner:tag:left:right: 
2-725 

setTransparent: method 2-121, 2-139 
setType: method 2-122, 2-139, 2-161 
setUnique: method 2-406 
setUpdateAction:forMenu: 2-305 
setVersion: method 2-38 
setVertCentered: method 2-475 
setVertPagination: method 2-475 
setVertResizable: method 2-606 
setVertScroller: method 2-518 
setVertScrollerRequired: method 2-518 
setwaitcursorenabled operator 4-38 
setwindowdepthlimit operator 4-39 
setwindowdict operator 4-40 
setwindowlevel operator 4-40 
setWindowsMenu: method 2-96 
setwindowtype operator 4-40 
set Works WhenModal: method 2-449 
setWrap: method 2-162 
setwriteblock operator 4-41 
sharedlnstance: method 2-358 
shouIdDrawColor method 2-675 
shouldRunPrintPanel: method 2-430 
showCaret method 2-606 
showcursor operator 4-41 
showGuessPanel: method 2-607 
showpage operator 4-42 
showsStateBy method 2-139 
signaturePort method 2-263 
single-operator functions 3-141 
sizeBy:: 2-675 
sizeimage operator 4-42 
sizelmage: method 2-311 
sizeimage: pixels Wide: pixelsHigh: 
bitsPerSample:samplesPerPixel:hasAlpha: 
isPlanancolorSpace: 2-312 
sizeTo:: 2-111, 2-176, 2-191, 2-233, 2-292,2-340, 
2-507, 2-607, 2-631, 2-676 
sizeToCells method 2-292 
sizeToFit method 2-111, 2-191, 2-233, 2-292, 
2-301, 2-340, 2-527, 2-607 
size Window:: 2-463, 2-726 
slavejournaler method 2-96 
Slider class 

specification 2-525 
SliderCell class 

specification 2-529 
smartFaxPSCode: method 2-726 
smartPrintPSCode: method 2-726 
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sound method 2-122,2-139 
Speaker class 

specification 2-537 
speaker method 2-421 

split View:getMinY:maxY:ofSubview At: 2-427 
splitView:resizeSubviews: 2-427 
splitViewDidResizeSubviews: method 2-428 
spoolFile: method 2-676, 2-727 
startArchiving: method 2-5 1 
startReadingRichText method 2-607 
startTrackingAt:inView: 2-162, 2-535 
startUnloading method 2-38 
state method 2-122, 2-162 
stilldown operator 4-43 
stop: method 2-96 
stopModal method 2-96 
stopModal: method 2-97 
stopTracking:at:inView:mouseIsUp: 2-162, 
2-535 

Storage class 

specification 2-53 
STR data type 1-27 
stream method 2-608 
StreamTable class 
specification 2-59 

stringValue method 2-70, 2-140,2-162, 2-191, 
2-535 

stringValueAt: method 2-233 

style method 2-202, 2-727 

subclassResponsibility: method 2-51 

submenu Action: method 2-302 

subscript: method 2-608 

subviews method 2-676 

superclass method 2-39, 2-51 

superscript: method 2-608 

superview method 2-676 

superviewSizeChanged: method 2-676 

suspendNotifyAncestorWhenFrameChanged: 

method 2-677 
Symtab data type 1-27 
systemLanguages method 2-97 

tag method 2-70, 2-162,2-191, 2-608,2-677 
takeColorFrom method 2-368 
takeDoubleValueFrom: method 2-163, 2-192 
takeFloatValueFrom: method 2-163, 2-192 
takelntValueFrom: method 2-163, 2-192 
takeStringValueFrom: method 2-163, 2-192 
target method 2-70, 2-164, 2-193, 2-293, 2-340, 
2-368, 2-464, 2-507 
terminate: method 2-97 
termwindow operator 4-43 
testPart: method 2-507 


Text class 

constants 2-618 
datatypes 2-618 
specification 2-557 
textColor method 2-608, 2-631 
textDelegate method 2-293,2-631 
textDidChange: method 2-293, 2-612, 2-631 
textDidEnd:endChar: 2-222,2-293,2-443,2-497, 
2-613,2-632 

textDidGetKeys:isEmpty: 2-222, 2-293, 2-497, 
2-613, 2-632 

textDidRead:paperSize: 2-613 
textDidResize :oldBounds invalid: 2-613 
TextField class 

specification 2-625 
TextFieldCell class 
specification 2-633 
textFilter method 2-609 
textGray method 2-609, 2-632, 2-637 
textLength method 2-609 
textWillChange: method 2-293, 2-444, 2-482, 
2-613, 2-632 

textWillConvert:fromFont:toFont: 2-614 
textWillEnd: method 2-294, 2-614, 2-632 
textWillFinishReadingRichText: method 2-614 
textWiI!ReadRichText:stream:atPosition: 2-614 
textWillResize: method 2-615 
textWillSetSektoFont: 2-615 
textWillStartReadingRichText: method 2-615 
textWillWrite:paperSize: 2-615 
textWillWriteRichText:stream:forRun: 

atPosition:emitDefaultRichText: 2-616 
tile method 2-340, 2-519 
timeout method 2-263 

title method 2-111, 2-122, 2-140, 2-238,2-727 
titleAlignment method 2-239 
titleAt: method 2-233 
titleFont method 2-239 
titleHeight method 2-340 
titleOfColumn: method 2-341 
titlePosition method 2-111 
titleWidth method 2-239 
title Width: method 2-239 
toggleRuler: method 2-609 
trackKnob: method 2-507 
trackMouse:inRect:ofView: 2-140,2-164,2-239, 
2-305, 2-535, 2-617, 2-637 
trackScrollButtons: method 2-507 
translate:: 2-176,2-677 
tryToPerform:with: 2-97, 2-488, 2-728 
type method 2-164 
TypedstreamErrors data type 1-27 
types method 2-457 
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underline: method 2-610 
unhide method 2-98, 2-263 
unhide: method 2-98 
unhideWithoutActivation: method 2-98 
unlockFocus method 2-406, 2-677 
unmounting:ok: 2-98, 2-264, 2-554 
unregisterWindow: method 2-264, 2-555 
unscript: method 2-610 
update method 2-193, 2-301,2-677, 2-728 
updateAction method 2-305 
updateCell: method 2-193 
updateCelllnside: method 2-193 
update Windows method 2-98 
updateWindowsltem: method 2-99 
useCacheWithDepth: method 2-406 
useDrawMethod:inObject: 2-407 
useFont: method 2-199 
useFromFile: method 2-407 
useFromSection: method 2-408 
useOptimizedDrawing: method 2-728 
usePrivatePort method 2-264 
useRepresentation: method 2-408 
useScrollBars: method 2-341 
useScrollButtons: method 2-341 

validateEditing method 2-193 
validateSize: method 2-294 
validateVisibleColumns method 2-341 
validRequestorForSendType:andReturnType: 

2-99, 2-488, 2-610, 2-729 
valueForKey: method 2-18 
valueForStreamKey: method 2-61 
valueForStringKey: method 2-29 
version method 2-39 
vertPagination method 2-476 
vertScroller method 2-519 
View class 

specification 2-639 

widthAdjustLimit method 2-678, 2-729 
Window class 

specification 2-681 
window method 2-678 
window operator 4-44 
windowChanged: method 2-611, 2-678 
windowdevice operator 4-45 
windowdeviceround operator 4-45 
windowDidBecomeKey: method 2-731 
windowDidBecomeMain: method 2-731 
windowDidChangeScreen: method 2-731 
windowDidDeminiaturize: method 2-731 
windowDidExpose: method 2-732 
windowDidMiniaturize: method 2-732 
windowDidMove: method 2-732 


windowDidResignKey: method 2-732 
windowDidResignMain: method 2-732 
windowDidResize: method 2-222, 2-733 
windowDidUpdate: method 2-733 
windowExposed: method 2-729 
windowList method 2-99 
windowlist operator 4-46 
windowMoved: method 2-301, 2-730 
windowNum method 2-730 
windowResized: method 2-730 
windowsMenu method 2-99 
windowWillClose: method 2-733 
windowWillMiniaturize:toMiniwindow: 2-733 
windowWillResize:toSize: 2-223, 2-733 
windowWillReturnFieldEditor:toObject: 2-734 
worksWhenModal method 2-223, 2-450, 2-730 
write: method 2-18, 2-26, 2-52, 2-58, 2-61, 2-70, 
2-111, 2-140, 2-165, 2-176, 2-193, 2-202, 2-239, 
2-265, 2-294, 2-302, 2-305, 2-321, 2-351, 2-374, 
2-377, 2-384, 2-409, 2-415, 2-476, 2-490, 2-508, 
2-519, 2-536, 2-555, 2-611, 2-632, 2-637, 2-678, 
2-731 

writePrintlnfo method 2-444, 2-482 
writeRichText: method 2-611 
writeRichText:forRun:atPosition: 

emitDefaultRichText: 2-611 
writeRichText:forView: 2-617 
writeRichText:from:to: 2-612 
writeSelectionToPasteboard:types: 2-431,2-612 
writeText: method 2-612 
writeTIFF: method 2-321, 2-409 
writeTIFF:allRepresentations: 2-409 
writeTIFF:usingCompression: 2-322 
writeTIFF:usingCompression:andFactor: 2-322 
writeToFile: method 2-30 
writeToStream: method 2-30 
writeType:data:length: 2-457 

zone method 2-52 
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NeXTStep Reference 

NeXTStep is the innovative object-oriented programming environment 
that makes it easy to develop advanced, user-oriented applications. 
NeXTStep enhances developer productivity by providing object-oriented 
building blocks that can be used in any application. 

NeXTStep Reference includes comprehensive descriptions of the Application 
Kit and other major components of NeXTStep: 

• Objective-C class specifications 

• Run-time system i for the Objective-C language 

• PostScript operations 

• Constants and data types 
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